From 430d324d9de305caed4af2325a127d3fd1420387 Mon Sep 17 00:00:00 2001 From: Jean Privat Date: Thu, 26 Apr 2012 13:40:39 -0400 Subject: [PATCH] lib: improve shortdoc of modules and fix some mistakes in existing comments. Signed-off-by: Jean Privat --- lib/opts.nit | 2 +- lib/standard/environ.nit | 6 +++--- lib/standard/exec.nit | 24 ++++++++++++------------ lib/standard/file.nit | 2 +- lib/standard/gc.nit | 14 ++++++++++++++ lib/standard/hash.nit | 8 ++++---- lib/standard/kernel.nit | 17 ++++++++++------- lib/standard/standard.nit | 3 ++- lib/standard/stream.nit | 2 +- lib/standard/string.nit | 26 ++++++++++++++------------ lib/standard/string_search.nit | 13 ++++++------- lib/standard/symbol.nit | 5 +++-- lib/standard/time.nit | 3 ++- 13 files changed, 73 insertions(+), 52 deletions(-) diff --git a/lib/opts.nit b/lib/opts.nit index 9d6eac1..f668ba3 100644 --- a/lib/opts.nit +++ b/lib/opts.nit @@ -11,7 +11,7 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# Manage options on the command line +# Management of options on the command line module opts # Super class of all option's class diff --git a/lib/standard/environ.nit b/lib/standard/environ.nit index 504f1d3..2617852 100644 --- a/lib/standard/environ.nit +++ b/lib/standard/environ.nit @@ -11,7 +11,7 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# Acces of the environement variables of the process +# Access to the environment variables of the process module environ import symbol @@ -19,8 +19,8 @@ import symbol # TODO prevoir une structure pour recup tout un environ, le modifier et le passer a process redef class Symbol - # Return environement value for this symbol - # If there is no such environement value, then return "" + # Return environment value for this symbol + # If there is no such environment value, then return "" fun environ: String do var res = to_s.to_cstring.get_environ diff --git a/lib/standard/exec.nit b/lib/standard/exec.nit index 2cde874..f71ce54 100644 --- a/lib/standard/exec.nit +++ b/lib/standard/exec.nit @@ -11,21 +11,21 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# This module handle simple system calls -# Standard input and output can be handleb trougth streams. +# Invocation and management of operating system sub-processes. +# Standard input and output can be handled through streams. package exec import stream -# Simple sub-processus +# Simple sub-process class Process - # The pid of the processus + # The pid of the process fun id: Int do return data.id - # Is the processus finished? + # Is the process finished? fun is_finished: Bool do return data.is_finished - # wait the terminaison of the process + # Wait the termination of the process fun wait do data.wait @@ -39,19 +39,19 @@ class Process return data.status end - # launch a command with some arguments + # Launch a command with some arguments init(command: String, arguments: String...) do execute(command, arguments, 0) end - # launch a simple command without arguments + # Launch a simple command without arguments init init_(command: String) do execute(command, null, 0) end - # Internal code to handle execusion + # Internal code to handle execution protected init execute(command: String, arguments: nullable Array[String], pipeflags: Int) do var args = new Buffer @@ -71,7 +71,7 @@ class Process private fun basic_exec_execute(p: NativeString, av: NativeString, ac: Int, pf: Int): NativeProcess is extern "exec_Process_Process_basic_exec_execute_4" end -# stdout of the processus is readable +# stdout of the process is readable class IProcess super Process super IStream @@ -96,7 +96,7 @@ class IProcess end end -# stdin of the processus is writable +# stdin of the process is writable class OProcess super Process super OStream @@ -149,7 +149,7 @@ class IOProcess end redef class Sys - # Execute a shell command and return it's error code + # Execute a shell command and return its error code fun system(command: String): Int do return command.to_cstring.system diff --git a/lib/standard/file.nit b/lib/standard/file.nit index d25a5c9..dc74b95 100644 --- a/lib/standard/file.nit +++ b/lib/standard/file.nit @@ -12,7 +12,7 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# This module handle file input and output +# File manipulations (create, read, write, etc.) package file intrude import stream diff --git a/lib/standard/gc.nit b/lib/standard/gc.nit index 4778bd8..1ffab48 100644 --- a/lib/standard/gc.nit +++ b/lib/standard/gc.nit @@ -1,5 +1,19 @@ +# This file is part of NIT ( http://www.nitlanguage.org ). +# +# This file is free software, which comes along with NIT. This software is +# distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; +# without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. You can modify it is you want, provided this header +# is kept unaltered, and a notification of the changes is added. +# You are allowed to redistribute it and sell it, alone or is a part of +# another product. + +# Access to the Nit internal garbage collection mechanism +module gc + import kernel redef class Sys + # Initiate a garbage collection fun force_garbage_collection is intern end diff --git a/lib/standard/hash.nit b/lib/standard/hash.nit index 67d2083..f8db8e6 100644 --- a/lib/standard/hash.nit +++ b/lib/standard/hash.nit @@ -10,17 +10,17 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# This module is about hashable things. -# It introduces an hash funtion in objects. +# Hashable things. +# It introduces an hash function in objects. package hash import kernel redef class Object # The hash code of the object. - # Assuming that a = b -> a.hash = b.hash + # Assuming that a == b -> a.hash == b.hash ## - # Without redefinition, it is the `id' of the instance. + # Without redefinition, it is based on the `object_id' of the instance. fun hash: Int do return object_id / 8 end diff --git a/lib/standard/kernel.nit b/lib/standard/kernel.nit index 9db559b..0c73352 100644 --- a/lib/standard/kernel.nit +++ b/lib/standard/kernel.nit @@ -11,6 +11,7 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. +# Most minimal classes and methods. # This module is the root of the standard module hierarchy. package kernel @@ -30,23 +31,24 @@ interface Object # The identifier is used internally to provide a hash value. fun object_id: Int is intern - # Return true is `self' and `other' have the same dynamic type. + # Return true if `self' and `other' have the same dynamic type. # Unless specific code, you should not use this method. fun is_same_type(other: Object): Bool is intern # Have `self' and `other' the same value? ## # The exact meaning of "same value" is let to the subclasses. - # Implicitly, the default implementation, is == + # Implicitly, the default implementation, is `is' fun ==(other: nullable Object): Bool do return self is other # Have `self' and `other' different values? ## - # != is equivalent with "not =". + # != is equivalent with "not ==". fun !=(other: nullable Object): Bool do return not (self == other) # Display self on stdout (debug only). - # This method MUST not be used by programs, it is here for debugging only and can be removed without any notice + # This method MUST not be used by programs, it is here for debugging + # only and can be removed without any notice fun output do '<'.output @@ -55,7 +57,8 @@ interface Object end # Display class name on stdout (debug only). - # This method MUST not be used by programs, it is here for debugging only and can be removed without any notice + # This method MUST not be used by programs, it is here for debugging + # only and can be removed without any notice fun output_class_name is intern # Quit the program with a specific return code @@ -149,10 +152,10 @@ interface Discrete # The previous element. fun prec: OTHER do return self - 1 - # The `i' th successor element. + # The `i'-th successor element. fun +(i: Int): OTHER is abstract - # The `i' th previous element. + # The `i'-th previous element. fun -(i: Int): OTHER is abstract # The distance between self and d. diff --git a/lib/standard/standard.nit b/lib/standard/standard.nit index 7c62c1b..5eb3fa3 100644 --- a/lib/standard/standard.nit +++ b/lib/standard/standard.nit @@ -11,7 +11,8 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# This module is implicitely imported by every module. +# Standard classes and methods used by default by Nit programs and libraries. +# This module is implicitly imported by every module. package standard import environ diff --git a/lib/standard/stream.nit b/lib/standard/stream.nit index dce2a89..38ac788 100644 --- a/lib/standard/stream.nit +++ b/lib/standard/stream.nit @@ -10,7 +10,7 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# This module handle abstract input and output streams +# Input and output streams of characters package stream import string diff --git a/lib/standard/string.nit b/lib/standard/string.nit index ae2af4a..c6a3e50 100644 --- a/lib/standard/string.nit +++ b/lib/standard/string.nit @@ -11,7 +11,7 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# This module is about character strings. +# Basic manipulations of strings of characters package string intrude import collection # FIXME should be collection::array @@ -53,7 +53,7 @@ abstract class AbstractString end end - # Create a substring with the string beginning at the 'from' position + # Create a substring from `self' beginning at the 'from' position # # "abcd".substring(1) # --> "bcd" # "abcd".substring(-1) # --> "abcd" @@ -64,7 +64,7 @@ abstract class AbstractString return substring(from, length - from) end - # is this string a substring of the 'of' string from pos 'pos' + # Is `self' a substring of the `str' string from pos `pos' # # "bc".is_substring("abcd",1) # --> true # "bc".is_substring("abcd",2) # --> false @@ -133,7 +133,7 @@ abstract class AbstractString end end - # String to upper case + # A upper case version of `self' fun to_upper: String do var s = new Buffer.with_capacity(length) @@ -141,7 +141,7 @@ abstract class AbstractString return s.to_s end - # String to lower case + # A lower case version of `self' fun to_lower : String do var s = new Buffer.with_capacity(length) @@ -160,7 +160,7 @@ abstract class AbstractString end end - +# Immutable strings of characters. class String super Comparable super AbstractString @@ -268,7 +268,7 @@ class String fun to_f : Float is extern import String::to_cstring end -# Strings are arrays of characters. +# Mutable strings of characters. class Buffer super AbstractString super Comparable @@ -398,8 +398,6 @@ end ############################################################################### redef class Object - # fun class_name: String is extern intern # The name of the class - # User readable representation of `self'. fun to_s: String do return inspect @@ -407,11 +405,13 @@ redef class Object private fun native_class_name: NativeString is intern # The class name of the object. - # FIXME: real type information is not available at runtime. Therefore, for instance, an instance of List[Bool] has just "List" for classname + # FIXME: real type information is not available at runtime. + # Therefore, for instance, an instance of List[Bool] has just + # "List" for class_name fun class_name: String do return new String.from_cstring(native_class_name) # Developer readable representation of `self'. - # Usualy, it uses the form "" + # Usually, it uses the form "" fun inspect: String do return "<{inspect_head}>" @@ -560,7 +560,9 @@ redef class Array[E] end redef class Map[K,V] - # Concatenate couple of 'key value' separate by 'couple_sep' and separate each couple with `sep'. + # Concatenate couple of 'key value'. + # key and value are separated by 'couple_sep'. + # each couple is separated each couple with `sep'. fun join(sep: String, couple_sep: String): String do if is_empty then return "" diff --git a/lib/standard/string_search.nit b/lib/standard/string_search.nit index 80cdabb..546fc62 100644 --- a/lib/standard/string_search.nit +++ b/lib/standard/string_search.nit @@ -10,13 +10,12 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# This module is about string search and matching. -# It includes some good features +# Basic string search, match and replace. package string_search import string -# Patterns are string motifs. +# Patterns are abstract string motifs (include `String' and `Char'). interface Pattern # Search `self' into `s' from a certain position. # Return the position of the first character of the matching section. @@ -58,10 +57,10 @@ interface Pattern end end -# BM_Pattern are precompiled string motif for the Boyer-Moore Fast String Searching Algorithm -# (cf. A Fast String Searching Algorithm, with R.S. Boyer. -# Communications of the Association for Computing Machinery, 20(10), 1977, pp. 762-772.) -# see also http://www.cs.utexas.edu/users/moore/best-ideas/string-searching/index.html +# BM_Pattern are pre-compiled string motif for the Boyer-Moore algorithm. +# (cf. A Fast String Searching Algorithm, with R.S. Boyer. Communications +# of the Association for Computing Machinery, 20(10), 1977, pp. 762-772.) +# http://www.cs.utexas.edu/users/moore/best-ideas/string-searching/index.html class BM_Pattern super Pattern diff --git a/lib/standard/symbol.nit b/lib/standard/symbol.nit index db15b75..e7fefc2 100644 --- a/lib/standard/symbol.nit +++ b/lib/standard/symbol.nit @@ -10,7 +10,8 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# This module introduce the Symbol class +# Symbol classes +# FIXME: Should be deprecated soon package symbol import string @@ -31,7 +32,7 @@ redef class String end end -# A symbol is a unique unmutable string +# A symbol is a unique immutable string class Symbol var _string: String redef fun to_s do return _string.to_s diff --git a/lib/standard/time.nit b/lib/standard/time.nit index 195157f..6e9c8c0 100644 --- a/lib/standard/time.nit +++ b/lib/standard/time.nit @@ -10,11 +10,12 @@ # You are allowed to redistribute it and sell it, alone or is a part of # another product. -# Manage time and dates +# Management of time and dates package time import kernel redef class Object + # Unix time: the number of seconds elapsed since January 1, 1970 protected fun get_time: Int is extern "kernel_Any_Any_get_time_0" end -- 1.7.9.5