Documentation

StdBool.dcl

 system module StdBool
 
+/**
+ * Class instances and basic functions for the Bool type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -16,7 +20,30 @@ instance fromBool		{#Char}
 
 //	Additional Logical Operators:
 
-not					:: !Bool		->	Bool	//	Not arg1
-(||)	infixr 2	:: !Bool Bool	->	Bool	//	Conditional or  of arg1 and arg2
-(&&)	infixr 3	:: !Bool Bool	->	Bool	//	Conditional and of arg1 and arg2
-
+/**
+ * Logical negation.
+ *
+ * @param The boolean to negate
+ * @result True if the parameter was False; False if True
+ */
+not					:: !Bool		->	Bool
+
+/**
+ * Logical disjunction. The second parameter is not strict and will not be
+ * evaluated if the first parameter is True.
+ *
+ * @param First boolean
+ * @param Second boolean
+ * @result True iff at least one of the parameters is True
+ */
+(||)	infixr 2	:: !Bool Bool	->	Bool
+
+/**
+ * Logical conjunction. The second parameter is not strict and will not be
+ * evaluated if the first parameter is False.
+ *
+ * @param First boolean
+ * @param Second boolean
+ * @result True iff both parameters are True
+ */
+(&&)	infixr 3	:: !Bool Bool	->	Bool

StdChar.dcl

 system module StdChar
 
+/**
+ * Class instances and basic functions for the Char type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -24,20 +28,116 @@ instance fromChar		{#Char}
 
 //	Additional conversions:
 
-digitToInt		:: !Char -> Int		//	Convert Digit into Int
-toUpper			:: !Char -> Char	//	Convert Char into an uppercase Char
-toLower			:: !Char -> Char	//	Convert Char into a  lowercase Char
+/**
+ * Converts a character from ['0'..'9'] to an integer.
+ *
+ * @param The character
+ * @result 0-9 if the character was from ['0'..'9'], otherwise another Int
+ */
+digitToInt		:: !Char -> Int
+
+/**
+ * Converts a character to uppercase.
+ *
+ * @param The character
+ * @result The same character, with bit 5 cleared
+ */
+toUpper			:: !Char -> Char
+
+/**
+ * Converts a character to lowercase.
+ *
+ * @param The character
+ * @result The same character, with bit 5 set
+ */
+toLower			:: !Char -> Char
 
 //	Tests on Characters:
 
-isUpper			:: !Char -> Bool	//	True if arg1 is an uppercase character
-isLower			:: !Char -> Bool	//	True if arg1 is a lowercase character
-isAlpha			:: !Char -> Bool	//	True if arg1 is a letter
-isAlphanum		:: !Char -> Bool	//	True if arg1 is an alphanumerical character
-isDigit			:: !Char -> Bool	//	True if arg1 is a digit
-isOctDigit		:: !Char -> Bool	//	True if arg1 is a digit
-isHexDigit		:: !Char -> Bool	//	True if arg1 is a digit
-isSpace			:: !Char -> Bool	//	True if arg1 is a space, tab etc
-isControl		:: !Char -> Bool	//	True if arg1 is a control character
-isPrint			:: !Char -> Bool	//	True if arg1 is a printable character
-isAscii			:: !Char -> Bool	//	True if arg1 is a 7 bit ASCII character
+/**
+ * Check for uppercase
+ *
+ * @param The character
+ * @result True iff the parameter is from ['A'..'Z']
+ */
+isUpper			:: !Char -> Bool
+
+/**
+ * Check for lowercase
+ *
+ * @param The character
+ * @result True iff the parameter is from ['a'..'z']
+ */
+isLower			:: !Char -> Bool
+
+/**
+ * Check for an alphabetic character
+ *
+ * @param The character
+ * @result True iff the parameter is from ['a'..'z'] ++ ['A'..'Z']
+ */
+isAlpha			:: !Char -> Bool
+
+/**
+ * Check for an alphabetic or numerical character
+ *
+ * @param The character
+ * @result True iff the parameter is from ['a'..'z'] ++ ['A'..'Z'] ++ ['0'..'9']
+ */
+isAlphanum		:: !Char -> Bool
+
+/**
+ * Check for a numerical character
+ *
+ * @param The character
+ * @result True iff the parameter is from ['0'..'9']
+ */
+isDigit			:: !Char -> Bool
+
+/**
+ * Check for an octal digit
+ *
+ * @param The character
+ * @result True iff the parameter is from ['0'..'7']
+ */
+isOctDigit		:: !Char -> Bool
+
+/**
+ * Check for a hexadecimal digit
+ *
+ * @param The character
+ * @result True iff the parameter is from ['0'..'9'] ++ ['a'..'f'] ++ ['A'..'F']
+ */
+isHexDigit		:: !Char -> Bool
+
+/**
+ * Check for whitespace
+ *
+ * @param The character
+ * @result True iff the parameter is one of ' ', '\t', '\n', '\r', '\f', '\v'
+ */
+isSpace			:: !Char -> Bool
+
+/**
+ * Check for an ASCII control character
+ *
+ * @param The character
+ * @result True iff the parameter is from ['\x00'..'\x1f'] ++ ['\x7f']
+ */
+isControl		:: !Char -> Bool
+
+/**
+ * Check for a printable ASCII character
+ *
+ * @param The character
+ * @result True iff the parameter is from [' '..'~']
+ */
+isPrint			:: !Char -> Bool
+
+/**
+ * Check for a 7-bit ASCII character
+ *
+ * @param The character
+ * @result True iff the integer value of the parameter is less than 128
+ */
+isAscii			:: !Char -> Bool

StdCharList.dcl

 definition module StdCharList
 
+/**
+ * Basic functions for manipulating lists of characters.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
 // ****************************************************************************************
 
-cjustify	:: !.Int ![.Char] -> .[Char] // Center [Char] in field with width arg1
-ljustify	:: !.Int ![.Char] -> .[Char] // Left justify [Char] in field with width arg1
-rjustify	:: !.Int ![.Char] -> [Char]	 // Right justify [Char] in field with width arg1
+/**
+ * Center-align a text with spaces, s.t. the right margin is 0 or 1 spaces
+ * longer than the left margin.
+ *
+ * @param The minimum length of the result
+ * @param The text to center
+ * @result A list of max(|param 2|, param 1), with param 2 surrounded by spaces
+ */
+cjustify	:: !.Int ![.Char] -> .[Char]
+
+/**
+ * Left-align a text with spaces
+ *
+ * @param The minimum length of the result
+ * @param The text to align
+ * @result A list of max(|param 2|, param 1), with spaces appended to param 2
+ */
+ljustify	:: !.Int ![.Char] -> .[Char]
+
+/**
+ * Right-align a text with spaces
+ *
+ * @param The minimum length of the result
+ * @param The text to align
+ * @result A list of max(|param 2|, param 1), with spaces prepended to param 2
+ */
+rjustify	:: !.Int ![.Char] -> [Char]
+
+/**
+ * Concatenate a list of texts, interspersing it with newlines
+ *
+ * @param The texts
+ * @result All texts concatenated, with newlines in between
+ */
+flatlines	:: ![[u:Char]] -> [u:Char]
 
-flatlines	:: ![[u:Char]] -> [u:Char]	 // Concatenate by adding newlines
-mklines 	:: ![Char] -> [[Char]]		 // Split in lines removing newlines
+/**
+ * Split a text on newlines
+ *
+ * @param The text
+ * @result A list of texts without newlines
+ */
+mklines 	:: ![Char] -> [[Char]]
 
-spaces		:: !.Int -> .[Char]			 // Make [Char] containing n space characters
+/**
+ * A list of a number of ' ' characters
+ *
+ * @param The number of characters
+ * @result A list of param 1 spaces
+ */
+spaces		:: !.Int -> .[Char]

StdDebug.dcl

 definition module StdDebug
 
+/**
+ * Functions that write intermediate results to stderr for debugging purposes.
+ */
+
 // ********************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -12,16 +16,48 @@ from StdString import instance toString	{#Char},instance toString Int
 // The following functions should only be used for debugging,
 // because these functions have side effects
 
-trace :: !msg .a -> .a | toString msg	// write toString msg to stderr
-										// before evaluating a
-										special msg={#Char}; msg=Int
-trace_n :: !msg .a -> .a | toString msg	// write toString msg and newline to stderr
-										// before evaluating a
-										special msg={#Char}; msg=Int
-
-trace_t :: !msg -> Bool | toString msg	// write toString msg to stderr
-										// result is True
-										special msg={#Char}; msg=Int
-trace_tn :: !msg -> Bool | toString msg	// write toString msg and newline to stderr
-										// result is True
-										special msg={#Char}; msg=Int
+/**
+ * Write a message to stderr before returning a value.
+ *
+ * @param The message to write to stderr
+ * @param The value to return
+ * @result Param 2
+ */
+trace :: !msg .a -> .a | toString msg special msg={#Char}; msg=Int
+
+/**
+ * Write a message and a newline to stderr before returning a value.
+ *
+ * @param The message to write to stderr
+ * @param The value to return
+ * @result Param 2
+ */
+trace_n :: !msg .a -> .a | toString msg special msg={#Char}; msg=Int
+
+/**
+ * Write a message to stderr and return True. This is useful in guards, for
+ * example:
+ *
+ * ```
+ * square x
+ * | trace_t x = x * x
+ * ```
+ *
+ * @param The message to write to stderr
+ * @result True
+ */
+trace_t :: !msg -> Bool | toString msg special msg={#Char}; msg=Int
+
+/**
+ * Write a message and a newline to stderr and return True. This is useful in
+ * guards, for example:
+ *
+ * ```
+ * square x
+ * | trace_tn x = x * x
+ * ```
+ *
+ * @param The message to write to stderr
+ * @result True
+ */
+trace_tn :: !msg -> Bool | toString msg special msg={#Char}; msg=Int

StdEnv.dcl

 definition module StdEnv
 
+/**
+ * Clean's official Standard Environment library.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen

StdFunc.dcl

@@ -5,19 +5,83 @@ definition module StdFunc
 //	Copyright 1998 University of Nijmegen
 // ****************************************************************************************
 
-id    :: !.a -> .a								// identity function
-const :: !.a .b -> .a							// constant function
+/**
+ * The identity function.
+ *
+ * @param A value
+ * @result The same value
+ */
+id    :: !.a -> .a
 
-//flip  :: !.(.a -> .(.b -> .c)) .b .a -> .c		// Flip arguments
+/**
+ * The constant function.
+ *
+ * @param A value
+ * @param Another value
+ * @result The first value
+ */
+const :: !.a .b -> .a
+
+/**
+ * Flip the arguments of a function. This is useful in function compositions.
+ *
+ * @type !.(.a -> .(.b -> .c)) .b .a -> .c
+ * @param A function
+ * @param The second argument to the function
+ * @param The first argument to the function
+ * @result The function, applied to its arguments
+ */
 flip f a b :== f b a
 
-(o) infixr  9 // ::  u:(.a -> .b) u:(.c -> .a) -> u:(.c -> .b) // Function composition
+/**
+ * Function composition.
+ *
+ * @type u:(.a -> .b) u:(.c -> .a) -> u:(.c -> .b)
+ * @param A function f
+ * @param A function g
+ * @result The function f o g, that is, f applied after g
+ */
+(o) infixr  9
 (o) f g :== \ x -> f (g x)
 
-twice			:: !(.a -> .a)   .a             -> .a		// f (f x)
-while			:: !(a -> .Bool) (a -> a) 	 a 	->  a		// while (p x) f (f x) 
-until			:: !(a -> .Bool) (a -> a) 	 a 	->  a		// f (f x) until (p x)
-iter			:: !Int 		 (.a -> .a) .a	-> .a		// f (f..(f x)..) 
+/**
+ * Apply a function twice.
+ *
+ * @param A function f
+ * @param A value x
+ * @result f (f x)
+ */
+twice			:: !(.a -> .a)   .a             -> .a
+
+/**
+ * Apply a function as long as a property holds.
+ *
+ * @param A property p
+ * @param A function f
+ * @param An initial value x
+ * @result x if not p x, otherwise while p f (f x)
+ */
+while			:: !(a -> .Bool) (a -> a) 	 a 	->  a
+
+/**
+ * Apply a function until a property holds.
+ *
+ * @param A property p
+ * @param A function f
+ * @param An initial value x
+ * @result x if p x, otherwise until p f (f x)
+ */
+until			:: !(a -> .Bool) (a -> a) 	 a 	->  a
+
+/**
+ * Apply a function a number of times.
+ *
+ * @param The number of iterations n
+ * @param The function
+ * @param The initial value
+ * @result The result of applying the function n times to the initial value
+ */
+iter			:: !Int 		 (.a -> .a) .a	-> .a
 
 //	Some handy functions for transforming unique states:
 

StdInt.dcl

 system module StdInt 
 
+/**
+ * Class instances and basic functions for the Int type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -48,11 +52,64 @@ instance lcm Int	//	Least common multiple
 
 //	Operators on Bits:
 
-(bitor)	infixl  6	:: !Int !Int 	->	Int 	//	Bitwise Or of arg1 and arg2
-(bitand) infixl 6	:: !Int !Int 	->	Int 	//	Bitwise And of arg1 and arg2
-(bitxor) infixl 6	:: !Int !Int 	->	Int 	//	Exclusive-Or arg1 with mask arg2
-(<<)	infix  7	:: !Int !Int 	->	Int 	//	Shift arg1 to the left arg2 bit places
-(>>)	infix  7	:: !Int !Int 	->	Int 	//	Shift arg1 to the right arg2 bit places
-bitnot				:: !Int 		->	Int 	//	One's complement of arg1
-
+/**
+ * Bitwise disjunction.
+ *
+ * @param The first integer
+ * @param The second integer
+ * @result An integer with exactly those bits set that at least one of the parameters has set
+ */
+(bitor)	infixl  6	:: !Int !Int 	->	Int
+
+/**
+ * Bitwise conjunction.
+ *
+ * @param The first integer
+ * @param The second integer
+ * @result An integer with exactly those bits set that both of the parameters have set
+ */
+(bitand) infixl 6	:: !Int !Int 	->	Int
+
+/**
+ * Bitwise exclusive disjunction.
+ *
+ * @param The first integer
+ * @param The second integer
+ * @result An integer with exactly those bits set that exactly one of the parameters has set
+ */
+(bitxor) infixl 6	:: !Int !Int 	->	Int
+
+/**
+ * Shift an integer to the left.
+ *
+ * @param The integer to shift
+ * @param The number of places to shift
+ * @result The result of the bitshift
+ */
+(<<)	infix  7	:: !Int !Int 	->	Int
+
+/**
+ * Shift an integer to the right.
+ *
+ * @param The integer to shift
+ * @param The number of places to shift
+ * @result The result of the bitshift
+ */
+(>>)	infix  7	:: !Int !Int 	->	Int
+
+/**
+ * Bitwise logical negation.
+ *
+ * @param An integer
+ * @param The one's complement of the parameter
+ */
+bitnot				:: !Int 		->	Int
+
+/**
+ * Compile-time macro to check for the integer length of the system.
+ *
+ * @param The value if the platform is 64-bit
+ * @param The value if the platform is 32-bit
+ * @result Either of the parameters, depending on the platform
+ */
 IF_INT_64_OR_32 int64 int32 :== int32;

StdMisc.dcl

 system module StdMisc
 
+/**
+ * Miscellaneous functions.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
 // ****************************************************************************************
 
-abort		:: !{#Char} -> .a				// stop reduction and print argument
-undef		:: .a							// fatal error, stop reduction.
+/**
+ * Print a message and abort the program.
+ *
+ * @param The message to print
+ * @result There is no result; the program will terminate
+ */
+abort		:: !{#Char} -> .a
+
+/**
+ * The undefined value.
+ *
+ * @result An attempt to evaluate the result will yield a runtime error.
+ */
+undef		:: .a

StdReal.dcl

 system module StdReal
 
+/**
+ * Class instances and basic functions for the Real type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -56,4 +60,10 @@ instance atanh		Real	//	Arc Hyperbolic Tangent, partial function, only defined i
 
 //	Additional conversion:
 
-entier			:: !Real		->	Int		//	Convert Real into Int by taking entier
+/**
+ * Imprecise conversion from Real to Int.
+ *
+ * @param A Real
+ * @result The largest integer smaller than the parameter
+ */
+entier			:: !Real		->	Int

StdString.dcl

 system module StdString
 
+/**
+ * Class instances and basic functions for the String type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -26,6 +30,21 @@ instance %			{#Char}
 
 instance +++		{#Char}							// string concatenation
 
-(+++.) infixr 5 :: !{#Char} !{#Char} -> .{#Char}	// string concatenation with unique result
-
-(:=) infixl 9 :: !{#Char} !(!Int,!Char) -> {#Char}	//	update i-th element with char
+/**
+ * Concatenate two strings with a unique result. This is similar to +++, except
+ * that the result type is unique.
+ *
+ * @param A string
+ * @param A string
+ * @result The concatenation of the two strings
+ */
+(+++.) infixr 5 :: !{#Char} !{#Char} -> .{#Char}
+
+/**
+ * Update a character in a string.
+ *
+ * @param The string
+ * @param A tuple of the index and the new character
+ * @result The new string, with the new character on the specified position
+ */
+(:=) infixl 9 :: !{#Char} !(!Int,!Char) -> {#Char}

StdTuple.dcl

 definition module StdTuple
 
+/**
+ * Class instances and basic functions for tuples.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -7,16 +11,49 @@ definition module StdTuple
 
 import StdClass