StdClass, StdFile, StdFunc, StdOrdList and _SystemArray

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,97 @@ 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

StdFunc.dcl

@@ -85,15 +85,40 @@ iter			:: !Int 		 (.a -> .a) .a	-> .a
 
 //	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)

StdOrdList.dcl

@@ -7,29 +7,61 @@ 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

_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))