Documentation

StdBool.dcl

 system module StdBool
 
+/**
+ * Class instances and basic functions for the Bool type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 3.0
 //	Copyright 2019 University of Nijmegen
@@ -16,8 +20,30 @@ instance fromBool		{#Char}	:: !Bool -> {#Char}					:== code { .d 0 1 b ; jsr Bto
 
 //	Additional Logical Operators:
 
+/**
+ * Logical negation.
+ *
+ * @param The boolean to negate
+ * @result True if the parameter was False; False if True
+ */
 not					:: !Bool		->	Bool						:== code { notB }
-												//	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 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 3.0
 //	Copyright 2019 University of Nijmegen
@@ -24,20 +28,116 @@ instance fromChar		{#Char}	:: !Char -> {#Char}			:== code { CtoAC }
 
 //	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]

StdClass.dcl

 definition module StdClass
 
+/**
+ * Meta-classes with derived functions.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -12,40 +16,73 @@ from StdBool import not
 //	For the time-being, macro definitions are used for this purpose
 //	This may cause misleading error messages in case of type errors 
 
+//* Meta-class describing interval types with an absolute zero.
 class PlusMin a | + , - , zero a
 
+//* Meta-class describing ratio types.
 class MultDiv a | * , / , one a
 
+//* Meta-class describing arithmetical types.
 class Arith a 	| PlusMin , MultDiv , abs , sign , ~ a 
 
+//* Meta-class describing types that can be incremented and decremented.
 class IncDec a	| + , - , one , zero a
 where
+  //* Increment a value by one.
   inc :: !a -> a | + , one a
   inc x :== x + one
 
+  //* Decrement a value by one.
   dec :: !a -> a | - , one a
   dec x :== x - one
 
+//* Meta-class describing types that can be enumerated.
 class Enum a | < , IncDec a
 
+/**
+ * Equality.
+ * @var The type for which values can be equated
+ */
 class Eq a | == a	
 where
+  /**
+   * Inequality.
+   * @result True iff the parameters are not equal
+   */
   (<>) infix  4 :: !a	!a	->	Bool | Eq a
   (<>) x y :== not (x == y)
 
+/**
+ * Ordering.
+ * @var The type that can be ordered.
+ */
 class Ord a	| < a
 where
+  /**
+   * Greater than.
+   * @result True iff the first value is strictly greater than the second value.
+   */
   (>) infix  4 :: !a !a	-> Bool | Ord a
   (>) x y  :== y < x 
 
+  /**
+   * Smaller than or equal to.
+   * @result True iff the first value is smaller than or equal to the second value.
+   */
   (<=) infix 4 :: !a !a -> Bool | Ord a
   (<=) x y :== not (y<x)
 
+  /**
+   * Greater than or equal to.
+   * @result True iff the first value is greater than or equal to the second value.
+   */
   (>=) infix 4 :: !a !a -> Bool | Ord a
   (>=) x y :== not (x<y) 
 
+  //* The minimum of two values.
   min::!a !a ->	a | Ord a
   min x y  :== case (x<y) of True = x; _ = y
 
+  //* The maximum of two values.
   max::!a !a ->	a | Ord a
   max x y  :== case (x<y) of True = y; _ = x

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

StdEnum.dcl

 definition module StdEnum
 
+/**
+ * This module must be imported if dotdot expressions are used.
+ * Then, the following constructs can be used:
+ *
+ * - `[from .. ]`         -> `{{_from}} from`
+ * - `[from .. to]`       -> `{{_from_to}} from to`
+ * - `[from, then .. ]`   -> `{{_from_then}} from then`
+ * - `[from, then .. to]` -> `{{_from_then_to}} from then to`
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
 // ****************************************************************************************
 
-/*
-	This module must be imported if dotdot expressions are used
-
-		[from .. ]			-> _from from
-		[from .. to]		-> _from_to from to
-		[from, then .. ]	-> _from_then from then
-		[from, then .. to]	-> _from_then_to from then to
-*/
-	
 import	_SystemEnum

StdEnv.dcl

 definition module StdEnv
 
+/**
+ * Clean's official Standard Environment library.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 3.0
 //	Copyright 2018 Radboud University

StdFile.dcl

 system module StdFile
 
+/**
+ * Functions to manipulate the file system with the File type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 3.0
 //	Copyright 2019 University of Nijmegen
@@ -7,110 +11,206 @@ system module StdFile
 
 //	File modes synonyms
 
-FReadText	:== 0	//	Read from a text file
-FWriteText	:== 1	//	Write to a text file
-FAppendText	:== 2	//	Append to an existing text file
-FReadData	:== 3	//	Read from a data file
-FWriteData	:== 4	//	Write to a data file
-FAppendData	:== 5	//	Append to an existing data file
+//* File mode: read text
+FReadText	:== 0
+
+//* File mode: write text
+FWriteText	:== 1
+
+//* File mode: append text
+FAppendText	:== 2
+
+//* File mode: read data
+FReadData	:== 3
+
+//* File mode: write data
+FWriteData	:== 4
+
+//* File mode: append data
+FAppendData	:== 5
 
 //	Seek modes synonyms
 
-FSeekSet	:== 0	//	New position is the seek offset
-FSeekCur	:== 1	//	New position is the current position plus the seek offset
-FSeekEnd	:== 2	//	New position is the size of the file plus the seek offset
+//* Seek mode: the new position is the seek offset
+FSeekSet	:== 0
 
-::	*Files
+//* Seek mode: the new position is the current position plus the seek offset
+FSeekCur	:== 1
 
-//	Acces to the FileSystem (Files)
+//* Seek mode: the new position is the size of the file plus the seek offset
+FSeekEnd	:== 2
 
+/**
+ * The filesystem environment, independent from *World. This type can only be
+ * used through the FileSystem and FileEnv classes.
+ */
+:: *Files
+
+/**
+ * Access to the filesystem.
+ *
+ * @var The unique type that is used to ensure purity.
+ */
 class FileSystem f where
+	/**
+	 * Opens a file for the first time in a certain mode.
+	 * @param The filename
+	 * @param The mode (read / write / append; text / data)
+	 * @param The {{`FileSystem`}} (usually {{`World`}})
+	 * @result A boolean indicating success
+	 * @result The {{`File`}}
+	 * @result The new {{`FileSystem`}}
+	 */
 	fopen :: !{#Char} !Int !*f -> (!Bool,!*File,!*f)
-			/*	Opens a file for the first time in a certain mode (read, write or append, text or data).
-				The boolean output parameter reports success or failure. */
+
+	/**
+	 * Closes a file.
+	 * @param The {{`File`}}
+	 * @param The {{`FileSystem`}}
+	 * @result A boolean indicating success
+	 * @result The new {{`FileSystem`}}
+	 */
 	fclose :: !*File !*f -> (!Bool,!*f)
-			/* Closes a file */
+
+	//* Open the 'Console' for reading and writing.
 	stdio  :: !*f -> (!*File,!*f)
-			/*	Open the 'Console' for reading and writing. */
+
+	/**
+	 * With `sfopen` a file can be opened for reading more than once. On a file
+	 * opened by `sfopen` only the operations beginning with `sf` can be used.
+	 * The `sf...` operations work just like the corresponding `f...`
+	 * operations. They can't be used for files opened with {{`fopen`} or
+	 * {{`freopen`}}.
+	 *
+	 * @param The filename
+	 * @param The mode (read; text / data)
+	 * @param The {{`FileSystem`}} (usually {{`World`}})
+	 * @result A boolean indicating success
+	 * @result The new {{`File`}}
+	 * @result The new {{`FileSystem`}}
+	 */
 	sfopen :: !{#Char} !Int !*f -> (!Bool,!File,!*f)
-			/*	With sfopen a file can be opened for reading more than once.
-				On a file opened by sfopen only the operations beginning with sf can be used.
-				The sf... operations work just like the corresponding f... operations.
-				They can't be used for files opened with fopen or freopen. */
 
 instance FileSystem Files
 instance FileSystem World
 
+/**
+ * An environment in which files can be dealt with.
+ *
+ * @var The unique type that is used to ensure purity.
+ */
 class FileEnv env where
 	accFiles :: !.(*Files -> (.x,*Files)) !*env -> (!.x,!*env)