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

StdFunc.dcl

 definition module StdFunc
 
+/**
+ * A number of general functions and functions dealing with functions.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 3.0
 //	Copyright 2018 Radboud University
@@ -9,15 +13,38 @@ import StdFunctions
 
 //	Some handy functions for transforming unique states:
 
-seq				:: ![.(.s -> .s)] .s -> .s					// fn-1 (..(f1 (f0 x))..)
-seqList			:: ![St .s .a] .s -> ([.a],.s)				// fn-1 (..(f1 (f0 x))..)
-
+/**
+ * Iterate a list of state functions.
+ *
+ * @param The functions
+ * @param The initial state
+ * @result The final state
+ */
+seq				:: ![.(.s -> .s)] .s -> .s
+
+/**
+ * Iterate a list of state functions with result
+ *
+ * @param The functions
+ * @param The initial state
+ * @result A list of results from the state function and the final state
+ */
+seqList			:: ![St .s .a] .s -> ([.a],.s)
+
+//* A function that updates a state and produces a result.
 :: St s a :== s -> *(a,s)
 
 // monadic style:
 
-(`bind`) infix 0 // :: w:(St .s .a) v:(.a -> .(St .s .b)) -> u:(St .s .b), [u <= v, u <= w]
+/**
+ * Monadic bind for the {{`St`}} type.
+ * @type w:(St .s .a) v:(.a -> .(St .s .b)) -> u:(St .s .b), [u <= v, u <= w]
+ */
+(`bind`) infix 0
 (`bind`) f g :== \st0 -> let (r,st1) = f st0 in g r st1
 
-// return :: u:a -> u:(St .s u:a)
+/**
+ * Monadic return for the {{`St`}} type.
+ * @type u:a -> u:(St .s u:a)
+ */
 return r :== \s -> (r,s)

StdFunctions.dcl

@@ -5,16 +5,29 @@ definition module StdFunctions
 //	Copyright 2018 Radboud University
 // ****************************************************************************************
 
-id    :: !.a -> .a								// identity function
-const :: !.a .b -> .a							// constant function
+//* The identity function.
+id    :: !.a -> .a
+//* Always returns the first argument.
+const :: !.a .b -> .a
 
-//flip  :: !.(.a -> .(.b -> .c)) .b .a -> .c		// Flip arguments
+/**
+ * Flips the arguments of a function. This is useful in function compositions.
+ * @type !.(.a -> .(.b -> .c)) .b .a -> .c
+ */
 flip f a b :== f b a
 
-(o) infixr  9 // ::  u:(.a -> .b) u:(.c -> .a) -> u:(.c -> .b) // Function composition
+/**
+ * Function composition: apply `f` after `g`.
+ * @type u:(.a -> .b) u:(.c -> .a) -> u:(.c -> .b)
+ */
+(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 the function argument twice.
+twice			:: !(.a -> .a)   .a             -> .a
+//* Apply the second argument as long as the first argument holds.
+while			:: !(a -> .Bool) (a -> a) 	 a 	->  a
+//* Apply the second argument until the first argument holds.
+until			:: !(a -> .Bool) (a -> a) 	 a 	->  a
+//* Apply a function a number of times.
+iter			:: !Int 		 (.a -> .a) .a	-> .a

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
@@ -49,17 +53,65 @@ instance lcm Int	//	Least common multiple
 
 //	Operators on Bits:
 
+/**
+ * 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							:== code { or% }
-					//	Bitwise Or of arg1 and arg2
+
+/**
+ * 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							:== code { and% }
-					//	Bitwise And of arg1 and arg2
+
+/**
+ * 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							:== code { xor% }
-					//	Exclusive-Or arg1 with mask arg2
+
+/**
+ * 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							:== code { shiftl% }
-					//	Shift arg1 to the left arg2 bit places
+
+/**
+ * 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							:== code { shiftr% }