LICENSE

+Unless explicitly stated otherwise, the following license applies to all files in this repository:
+
+Copyright 2020 Radboud University Nijmegen. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY Radboud University Nijmegen ''AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Radboud University OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those of the
+authors and should not be interpreted as representing official policies, either expressed
+or implied, of Radboud University Nijmegen.
\ No newline at end of file

README.md

+# StdEnv-doc
+
+This is an annotated version of [Clean][]'s [StdEnv][] library for use in
+[Cloogle][].
+
+All code is copyright © 1998 University of Nijmegen.
+
+[Clean]: http://clean.cs.ru.nl
+[Cloogle]: https://cloogle.org
+[StdEnv]: https://svn.cs.ru.nl/repos/clean-libraries/trunk/Libraries/StdEnv/

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% }
-					//	Shift arg1 to the right arg2 bit places
+
+/**
+ * Bitwise logical negation.
+ *
+ * @param An integer
+ * @param The one's complement of the parameter
+ */
 bitnot				:: !Int 		->	Int							:== code { not% }
-					//	One's complement of arg1
 
-IF_INT_64_OR_32 int64 int32 :== int32;
+/**
+ * Compile-time macro to check for the integer length of the system.
+ *
+ * @type .a .a -> .a
+ * @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 :== int64;

StdMaybe.dcl

@@ -6,31 +6,43 @@ definition module StdMaybe
 
 from StdOverloaded import class ==(..);
 
+/**
+ * The Maybe type represents an optional value by providing a constructor
+ * for no value (`Nothing`) and a constructor for just a value (`Just`).
+ */
 ::	Maybe x
 	=	Just x
 	|	Nothing
 
-isJust		:: !(Maybe .x) -> Bool		// case @1 of (Just _) -> True; _ -> False
-isNothing	:: !(Maybe .x) -> Bool		// not o isJust
-fromJust	:: !(Maybe .x) -> .x		// \(Just x) -> x
+//* `case @1 of ({{Just}} _) -> True; _ -> False`
+isJust		:: !(Maybe .x) -> Bool
 
-// for possibly unique elements:
+//* `{{not}} {{o}} {{isJust}}`
+isNothing	:: !(Maybe .x) -> Bool
+
+//* `\({{Just}} x) -> x`
+fromJust	:: !(Maybe .x) -> .x
+
+//* {{`isJust`}} for a possibly unique value.
 isJustU :: !u:(Maybe .x) -> (!Bool, !u:Maybe .x)
+
+//* {{`isNothing`}} for a possibly unique value.
 isNothingU :: !u:(Maybe .x) -> (!Bool, !u:Maybe .x)
 
+//* Apply a function on the value boxed in {{`Just`}}, or pass on {{`Nothing`}}.
 mapMaybe	:: .(.x -> .y) !(Maybe .x) -> Maybe .y
-// mapMaybe f (Just x) = Just (f x)
-// mapMaybe f Nothing  = Nothing
 
 instance == (Maybe x) | == x
-//	Nothing==Nothing
-//	Just a ==Just b <= a==b
 
+/**
+ * @result A list with no or one element.
+ */
 maybeToList :: !(Maybe .a) -> [.a];
-//	returns list with no or one element
 
+/**
+ * @result {{`Just`}} the head of the list or {{`Nothing`}} if it is empty.
+ */
 listToMaybe :: ![.a] -> .Maybe .a;
-//	returns Just head of list if possible
 
+//* `catMaybes ms = [m \\ {{Just}} m <- ms]`
 catMaybes :: ![Maybe .a] -> .[.a];
-//	catMaybes ms =  [ m \\ Just m <- ms ]

StdMisc.dcl

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

StdOrdList.dcl

 definition module StdOrdList
 
+/**
+ * Functions to work with lists of elements for which an ordering exists.
+ */
+
 //	****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
@@ -7,29 +11,53 @@ definition module StdOrdList
 
 import StdClass
 
-sort    ::               !u:[a] -> u:[a] | Ord a			// Sort the list (mergesort)
+//* Sort a list (mergesort).
+sort    ::               !u:[a] -> u:[a] | Ord a
 	special
 		a	= Char
 		a	= Int
 		a	= Real
-sortBy  :: (a a -> Bool) !u:[a] -> u:[a] 					// Sort the list, arg1 is < function
-merge   ::               !u:[a] !v:[a] -> w:[a]	
-										 | Ord a,[u v <= w] // Merge two sorted lists giving a sorted list
+
+/**
+ * Sort a list using a custom ordering.
+ * @param The custom {{`<`}} function
+ */
+sortBy  :: (a a -> Bool) !u:[a] -> u:[a]
+
+//* Merge two sorted lists.
+merge   ::               !u:[a] !v:[a] -> w:[a] | Ord a,[u v <= w]
 	special
 		a	= Char
 		a	= Int
 		a	= Real
-mergeBy :: (a a -> Bool) !u:[a] !v:[a] -> w:[a]				// Merge two sorted lists giving a sorted list
-										 ,[u v <= w]		// arg1 is < function
-maxList	:: !.[a] 			-> a 		 | Ord a			// Maximum element of list
+
+/**
+ * Merge two sorted lists using a custom ordering.
+ * @param The custom {{`<`}} function
+ */
+mergeBy :: (a a -> Bool) !u:[a] !v:[a] -> w:[a],[u v <= w]
+
+//* The maximum element of a list.
+maxList	:: !.[a] 			-> a 		 | Ord a
 	special
 		a	= Char
 		a	= Int
 		a	= Real
-maxListBy :: (a a -> Bool) !.[a] -> a						// Maximum element of list, arg1 is < function
-minList	:: !.[a] 			-> a 		 | Ord a			// Minimum element of list
+
+/**
+ * The maximum element of a list using a custom ordering.
+ * @param The custom {{`<`}} function
+ */
+maxListBy :: (a a -> Bool) !.[a] -> a
+
+//* The minimum element of a list.
+minList	:: !.[a] 			-> a 		 | Ord a
 	special
 		a	= Char
 		a	= Int
 		a	= Real
-minListBy :: (a a -> Bool) !.[a] -> a						// Minimum element of list, arg1 is < function
+/**
+ * The minimum element of a list using a custom ordering.
+ * @param The custom {{`<`}} function
+ */
+minListBy :: (a a -> Bool) !.[a] -> a

StdOverloaded.dcl

 definition module StdOverloaded
 
+/**
+ * A number of common overloaded functions.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 2.0
 //	Copyright 1998 University of Nijmegen
 // ****************************************************************************************
 
-class (+)  infixl 6	a	:: !a	!a	->	a				//	Add arg1 to arg2
+//* Add `arg1` to `arg2`.
+class  (+)  infixl 6	a	:: !a	!a	->	a
+
+//* Subtract `arg2` from `arg1`.
+class  (-)  infixl 6	a	:: !a	!a	->	a
+
+//* Zero (unit element for addition).
+class  zero 			a	:: a
+
+
+//* Multiply `arg1` with `arg2`.
+class  (*)  infixl 7	a	:: !a	!a	->	a
+
+//* Divide `arg1` by `arg2`.
+class  (/)  infixl 7	a	:: !a	!a	->	a
+
+//* One (unit element for multiplication).
+class  one 			a	:: a
+
+
+//* True if `arg1` is equal to `arg2`.
+class  (==) infix  4	a	:: !a	!a	->	Bool
+
+//* True if `arg1` is less than `arg2`.
+class  (<)  infix  4	a	:: !a	!a	->	Bool
+
+//* True if `arg1` is an even number.
+class  isEven a :: !a -> Bool;
+
+//* True if `arg1` is an odd  number.
+class  isOdd  a :: !a -> Bool;
+
+
+/**
+ * Number of elements in `arg`.
+ * Used for list-like structures. It should have O(n) complexity.
+ */
+class  length m	:: !(m a) -> Int
+
+//* Slice a part from `arg1`.
+class  (%)  infixl 9	a	:: !a !(!Int,!Int)	-> a
+
+
+//* Append the arguments.
+class  (+++) infixr 5	a 	:: !a	!a	-> a
+
+
+//* `arg1` to the power of `arg2`.
+class  (^)  infixr 8	a	:: !a	!a 	->	a
+
+//* Absolute value.
+class  abs  			a	:: !a		->	a
+
+/**
+ * The sign of a thing.
+ * @result `1` for a positive value; `-1` for a negative value; `0` for zero
+ */
+class  sign 			a	:: !a 		->	Int
+
+//* Negate a thing.
+class  ~				a	:: !a 		->	a
+
 
-class (-)  infixl 6	a	:: !a	!a	->	a 				//	Subtract arg2 from arg1
-class zero 			a	:: a							//	Zero (unit element for addition)
+//* `arg1` modulo `arg2`.
+class  (mod) infix 7 a :: !a !a -> a
 
-class (*)  infixl 7	a	:: !a	!a	->	a				//	Multiply arg1 with arg2
-class (/)  infixl 7	a	:: !a	!a	->	a				//	Divide arg1 by arg2
-class one 			a	:: a							//	One (unit element for multiplication)
+//* The remainder after division of `arg1 / arg2`.
+class  (rem)	infix 7	a :: !a !a -> a
 
-class (==) infix  4	a	:: !a	!a	->	Bool			//	True if arg1 is equal to arg2
-class (<)  infix  4	a	:: !a	!a	->	Bool	 		//	True if arg1 is less than arg2
-class isEven a :: !a -> Bool;							// True if arg1 is an even number
-class isOdd  a :: !a -> Bool;							// True if arg1 is an odd  number
+//* Greatest common divisor.
+class  gcd a :: !a !a -> a
 
-class length m	:: !(m a) -> Int						//	Number of elements in arg
-														//	used for list like structures (linear time)
+//* Least common multiple.
+class  lcm a :: !a !a -> a
 
-class (%)  infixl 9	a	:: !a !(!Int,!Int)	-> a		//	Slice a part from arg1
 
-class (+++) infixr 5	a 	:: !a	!a	-> a			//	Append args
+//* Convert into {{`Int`}}.
+class  toInt			a	:: !a		->	Int
 
-class (^)  infixr 8	a	:: !a	!a 	->	a				//	arg1 to the power of arg2
-class abs  			a	:: !a		->	a				//	Absolute value
-class sign 			a	:: !a 		->	Int				//	1 (pos value) -1 (neg value) 0 (if zero)
-class ~				a	:: !a 		->	a				//	-a1
+//* Convert into {{`Char`}}.
+class  toChar		a	:: !a		->	Char
 
-class (mod) infix 7 a :: !a !a -> a						//	arg1 modulo arg2
-class (rem)	infix 7	a :: !a !a -> a 					//	remainder after division
-class gcd a :: !a !a -> a								//	Greatest common divider
-class lcm a :: !a !a -> a								//	Least common multiple
+//* Convert into {{`Bool`}}.
+class  toBool		a	:: !a		->	Bool
 
-class toInt			a	:: !a		->	Int				//	Convert into Int
-class toChar		a	:: !a		->	Char			//	Convert into Char
-class toBool		a	:: !a		->	Bool			//	Convert into Bool
-class toReal		a	:: !a		->	Real			//	Convert into Real
-class toString		a	:: !a		->	{#Char}			//	Convert into String
+//* Convert into {{`Real`}}.
+class  toReal		a	:: !a		->	Real
 
-class fromInt		a	:: !Int			-> a			//	Convert from Int
-class fromChar		a	:: !Char		-> a			//	Convert from Char
-class fromBool		a	:: !Bool		-> a			//	Convert from Bool
-class fromReal		a	:: !Real		-> a			//	Convert from Real
-class fromString	a	:: !{#Char}		-> a			//	Convert from String
+//* Convert into {{`String`}}.
+class  toString		a	:: !a		->	{#Char}
+
+
+//* Convert from {{`Int`}}.
+class  fromInt		a	:: !Int			-> a
+
+//* Convert from {{`Char`}}.
+class  fromChar		a	:: !Char		-> a
+
+//* Convert from {{`Bool`}}.
+class  fromBool		a	:: !Bool		-> a
+
+//* Convert from {{`Real`}}.
+class  fromReal		a	:: !Real		-> a
+
+//* Convert from {{`String`}}.
+class  fromString	a	:: !{#Char}		-> a
+
+
+//* Logarithm base e.
+class  ln			a	:: !a 		->	a
+
+//* Logarithm base 10.
+class  log10			a	:: !a 		->	a
+
+//* e to to the power of `arg`.
+class  exp			a	:: !a 		->	a
+
+//* Square root.
+class  sqrt			a	:: !a 		->	a
 
-class ln			a	:: !a 		->	a				//	Logarithm base e
-class log10			a	:: !a 		->	a				//	Logarithm base 10
-class exp			a	:: !a 		->	a				//	e to to the power	
-class sqrt			a	:: !a 		->	a				//	Square root
 
 //	Trigonometrical Functions:
 
-class sin			a	:: !a		->	a				//	Sine
-class cos			a	:: !a		->	a				//	Cosine
-class tan			a	:: !a		->	a				//	Tangent
-class asin			a	:: !a		->	a				//	Arc Sine
-class acos			a	:: !a		->	a				//	Arc Cosine
-class atan			a	:: !a		->	a				//	Arc Tangent
-class sinh			a	:: !a		->	a				//	Hyperbolic Sine
-class cosh			a	:: !a		->	a				//	Hyperbolic Cosine
-class tanh			a	:: !a		->	a				//	Hyperbolic Tangent
-class asinh			a	:: !a		->	a				//	Arc Hyperbolic Sine
-class acosh			a	:: !a		->	a				//	Arc Hyperbolic Cosine
-class atanh			a	:: !a		->	a				//	Arc Hyperbolic Tangent
+//* Sine.
+class  sin			a	:: !a		->	a
+
+//* Cosine.
+class  cos			a	:: !a		->	a
+
+//* Tangent.
+class  tan			a	:: !a		->	a
+
+//* Arc Sine.
+class  asin			a	:: !a		->	a
+
+//* Arc Cosine.
+class  acos			a	:: !a		->	a
+
+//* Arc Tangent.
+class  atan			a	:: !a		->	a
+
+//* Hyperbolic Sine.
+class  sinh			a	:: !a		->	a
+
+//* Hyperbolic Cosine.
+class  cosh			a	:: !a		->	a
+
+//* Hyperbolic Tangent.
+class  tanh			a	:: !a		->	a
+
+//* Arc Hyperbolic Sine.
+class  asinh			a	:: !a		->	a
+
+//* Arc Hyperbolic Cosine.
+class  acosh			a	:: !a		->	a
+
+//* Arc Hyperbolic Tangent.
+class  atanh			a	:: !a		->	a

StdReal.dcl

 system module StdReal
 
+/**
+ * Class instances and basic functions for the Real type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 3.0
 //	Copyright 2019 University of Nijmegen
@@ -66,8 +70,14 @@ instance atanh		Real	//	Arc Hyperbolic Tangent, partial function, only defined i
 
 //	Additional conversion:
 
+/**
+ * Imprecise conversion from Real to Int.
+ *
+ * @param A Real
+ * @result The largest integer smaller than the parameter
+ */
 entier			:: !Real -> Int									:== code { entierR }
-							//	Convert Real into Int by taking entier
+
 
 Infinity :== 1E9999
 NaN :== 1E9999+(-1E9999)

StdString.dcl

 system module StdString
 
+/**
+ * Class instances and basic functions for the String type.
+ */
+
 // ****************************************************************************************
 //	Concurrent Clean Standard Library Module Version 3.0
 //	Copyright 2019 University of Nijmegen
@@ -27,8 +31,21 @@ instance %			{#Char}	:: !{#Char} !(!Int,!Int) -> {#Char}				:== code { .d 1 2 ii
 instance +++		{#Char}	:: !{#Char} !{#Char} -> {#Char}					:== code { .d 2 0 ; jsr catAC ; .o 1 0 }
 													// string concatenation
 
+/**
+ * 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}							:== code { .d 2 0 ; jsr catAC ; .o 1 0 }
-													// string concatenation with unique result
 
+/**
+ * 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}							:== code { .d 1 2 ic ; jsr updateAC ; .o 1 0 }
-													//	update i-th element with 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
 
-// fst		:: !(!.a,.b) -> .a								// t1 of (t1,t2)
+/**
+ * The first element of a two-tuple.
+ *
+ * @type !(!.a,.b) -> .a
+ * @param The tuple
+ * @result The first element
+ */
 fst tuple :== t1 where (t1, _) = tuple
-// snd		:: !(.a,!.b) -> .b								// t2 of (t1,t2)
+
+/**
+ * The second element of a two-tuple.
+ *
+ * @type !(.a,!.b) -> .b
+ * @param The tuple
+ * @result The second element
+ */
 snd tuple :== t2 where (_, t2) = tuple
 
-// fst3	:: !(!.a,.b,.c) -> .a								// t1 of (t1,t2,t3)
+/**
+ * The first element of a three-tuple.
+ *
+ * @type !(!.a,.b,.c) -> .a
+ * @param The tuple
+ * @result The first element
+ */
 fst3 tuple :== t1 where (t1, _, _) = tuple
-// snd3	:: !(.a,!.b,.c) -> .b								// t2 of (t1,t2,t3)
+
+/**
+ * The second element of a three-tuple.
+ *
+ * @type !(.a,!.b,.c) -> .b
+ * @param The tuple
+ * @result The second element
+ */
 snd3 tuple :== t2 where (_, t2, _) = tuple
-// thd3	:: !(.a,.b,!.c) -> .c								// t3 of (t1,t2,t3)
+
+/**
+ * The third element of a three-tuple.
+ *
+ * @type !(.a,.b,!.c) -> .c
+ * @param The tuple
+ * @result The third element
+ */
 thd3 tuple :== t3 where (_, _, t3) = tuple
 
 instance == ()                              :: !() !() -> Bool :== code { pop_a 2 ; pushB TRUE }
@@ -27,9 +64,39 @@ instance <  ()                              :: !() !() -> Bool :== code { pop_a
 instance <  (a,b)   | Ord a & Ord b			:: !(!a,b) !(!a,b) -> Bool | Ord a & Ord b
 instance <  (a,b,c) | Ord a & Ord b & Ord c	:: !(!a,b,c) !(!a,b,c) -> Bool | Ord a & Ord b & Ord c
 
-app2 	:: !(.(.a -> .b),.(.c -> .d)) !(.a,.c) -> (.b,.d)	// app2 (f,g) (a,b) = (f a,g b)
+/**
+ * Apply functions to both elements of a two-tuple.
+ *
+ * @param A tuple of functions (f,g)
+ * @param A tuple of values (x,y)
+ * @result The tuple of the result of the applications (f x,g y)
+ */
+app2 	:: !(.(.a -> .b),.(.c -> .d)) !(.a,.c) -> (.b,.d)
+
+/**
+ * Apply functions to all elements of a three-tuple.
+ *
+ * @param A tuple of functions (f,g,h)
+ * @param A tuple of values (x,y,z)
+ * @result The tuple of the result of the applications (f x,g y,h z)
+ */
 app3 	:: !(.(.a -> .b),.(.c -> .d),.(.e -> .f)) !(.a,.c,.e) -> (.b,.d,.f)
-															// app3 (f,g,h) (a,b,c) = (f a,g b,h c)
 
-curry	:: !.((.a,.b) -> .c) .a .b -> .c					// curry f a b	= f (a,b)
-uncurry :: !.(.a -> .(.b -> .c)) !(.a,.b) -> .c				// uncurry f (a,b)	= f a b
+/**
+ * Apply a function that takes a two-tuple to two separate values.
+ *
+ * @param A function f
+ * @param The first element of the parameter tuple x
+ * @param The second element of the parameter tuple y
+ * @result f applied to (x,y)
+ */
+curry	:: !.((.a,.b) -> .c) .a .b -> .c
+
+/**
+ * Apply a function for two separate values to a two-tuple.
+ *
+ * @param A function f
+ * @param A tuple of parameters (x,y)
+ * @result The application f x y.
+ */
+uncurry :: !.(.a -> .(.b -> .c)) !(.a,.b) -> .c

_SystemArray.dcl

 definition module _SystemArray
 
+/**
+ * Operations on arrays.
+ * This is an internal class used to overload operations on different types of
+ * arrays. It should not be instantiated outside of this module.
+ */
 class Array .a e where
+	/**
+	 * Select an element from an array.
+	 * This is the function underlying the {{`.[]`}} construct.
+	 * Also see {{`uselect`}}.
+	 */
 	select				:: !.(a .e) !Int	-> .e
+
+	/**
+	 * Select an element from a unique array.
+	 * This is the function underlying the {{`![]`}} construct.
+	 * Also see {{`select`}}.
+	 */
 	uselect				:: !u:(a e) !Int	-> *(e, !u:(a e))
+
+	/**
+	 * The size of an array.
+	 * Also see {{`usize`}}.
+	 */
 	size				:: !.(a .e)			-> Int
+
+	/**
+	 * The size of a unique array.
+	 * Also see {{`size`}}.
+	 */
 	usize				:: !u:(a .e)		-> *(!Int, !u:(a .e))
+
+	/**
+	 * Update an element in a unique array.
+	 * This is the function underlying the {{`&`}} construct.
+	 * Also see {{`replace`}}.
+	 * @param The array
+	 * @param The index to update
+	 * @param The new element
+	 * @result The new array
+	 */
 	update				:: !*(a .e) !Int .e -> *(a .e)	
+
+	/**
+	 * Create a new array. Also see {{`_createArray`}}.
+	 * @param The number of elements
+	 * @param The elements
+	 * @result The array
+	 */
 	createArray			:: !Int e			-> *(a e)
+
+	/**
+	 * Create an empty array of a certain size. Also see {{`createArray`}}.
+	 * @param The number of elements
+	 * @result The array
+	 */
 	_createArray		:: !Int				-> *(a .e)
+
+	/**
+	 * Replace an element in an array and return the previous value.
+	 * Also see {{`update`}}.
+	 * @param The array
+	 * @param The index to update
+	 * @param The new value
+	 * @result The old value
+	 * @result The new array
+	 */
 	replace				:: !*(a .e) !Int .e -> *(.e, !*(a .e))
 
 instance Array {!} a where
@@ -76,4 +135,10 @@ instance Array {32#} Real where
 	createArray :: !Int !Real -> *{32# Real}
 	replace :: !*{32# e:Real} !Int !e:Real -> *(!e:Real, !*{32# e:Real})
 
+instance Array {32#} a where
+	uselect :: !u:{32# e} !Int -> *(!e, !u:{32# e})
+	update :: !*{32# .e} !Int !.e -> *{32# .e}
+	createArray :: !Int !e -> *{32# e}
+	replace :: !*{32# .e} !Int !.e -> *(!.e, !*{32# .e})
+
 instance Array {} a

_SystemArray.icl

@@ -520,6 +520,84 @@ instance Array {32#} Int where
 			create_array_ INT32 0 1
 		}
 
+instance Array {32#} a where
+	select arr index =
+		code
+		{
+			buildAC "StdArray:select ({32#} a) should not be called"
+		.d 1 0
+			jsr print_string_
+		.o 0 0
+			halt
+		}
+	uselect :: !u:{32# e} !Int -> *(!e, !u:{32# e})
+	uselect arr index =
+		code
+		{
+			buildAC "StdArray:uselect ({32#} a) should not be called"
+		.d 1 0
+			jsr print_string_
+		.o 0 0
+			halt
+		}
+	size arr =
+		code
+		{
+			buildAC "StdArray:size ({32#} a) should not be called"
+		.d 1 0
+			jsr print_string_
+		.o 0 0
+			halt
+		}
+	usize arr =
+		code
+		{
+			buildAC "StdArray:usize ({32#} a) should not be called"
+		.d 1 0
+			jsr print_string_
+		.o 0 0
+			halt
+		}
+	update :: !*{32# .e} !Int !.e -> *{32# .e}
+	update arr index el =
+		code
+		{
+			buildAC "StdArray:update ({32#} a) should not be called"
+		.d 1 0
+			jsr print_string_
+		.o 0 0
+			halt
+		}
+	createArray :: !Int !e -> *{32# e}
+	createArray size el =
+		code
+		{
+			buildAC "StdArray:createArray ({32#} a) should not be called"
+		.d 1 0
+			jsr print_string_
+		.o 0 0
+			halt
+		}
+	replace :: !*{32# .e} !Int !.e -> *(!.e, !*{32# .e})
+	replace arr index el =
+		code
+		{
+			buildAC "StdArray:replace ({32#} a) should not be called"
+		.d 1 0
+			jsr print_string_
+		.o 0 0
+			halt
+		}
+	_createArray size =
+		code
+		{
+			buildAC "StdArray:_createArray ({32#} a) should not be called"
+		.d 1 0
+			jsr print_string_
+		.o 0 0
+			halt
+		}
+
 instance Array {!} a where
 	select arr index =
 		code

_SystemEnum.dcl

 definition module _SystemEnum
 
+/**
+ * The underlying functions for dotdot expressions.
+ *
+ * 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
-*/
-
 from StdClass import class Enum (..), class IncDec (..), class Ord (..),<=,inc,dec
 from StdBool import not 
 import StdInt,StdChar
 
+/**
+ * Generate a list of all values from a starting point.
+ * Instead of `_from x`, you can use `[x..]`.
+ *
+ * @param The starting point
+ * @result [x, x + one, x + one + one, x + one + one + one, ...]
+ */
 _from			::  a		-> .[a] | IncDec , Ord a	special a=Int; a=Char
+
+/**
+ * Generate a list of all values from a starting point to an endpoint.
+ * Instead of `_from_to x y`, you can use `[x..y]`.
+ *
+ * @param The starting point
+ * @param The endpoint
+ * @result [x, inc x, inc (inc x), inc (inc (inc x)), ..., E] where E <= y
+ */
 _from_to		:: !a !a	-> .[a] | Enum a			special a=Int; a=Char
+
+/**
+ * Generate a list of all values from a starting point with a certain interval.
+ * Instead of `_from_then x y`, you can use `[x,y..]`.
+ *
+ * @param The starting point
+ * @param The next point
+ * @result [x, y, x + (y - x) + (y - x), ...]
+ */
 _from_then		::  a  a	-> .[a] | Enum a			special a=Int; a=Char
+
+/**
+ * Generate a list of all values from a starting point to an endpoint with a
+ * certain interval.
+ * Instead of `_from_then_to x y z`, you can use `[x,y..z]`.
+ *
+ * @param The starting point
+ * @param The next point
+ * @param The endpoint
+ * @result [x, y, x + (y - x) + (y - x), ..., E] where E <= z
+ */
 _from_then_to	:: !a !a !a	-> .[a] | Enum a			special a=Int; a=Char