More documentation

src/libraries/OS-Independent/Data/Error.dcl

@@ -5,8 +5,17 @@ from Control.Monad import class Monad
 from Control.Applicative import class Applicative
 from Data.Maybe import :: Maybe
 
+/**
+ * A type representing something that may have failed.
+ * @var The error type.
+ * @var The value type.
+ */
 :: MaybeError a b = Error a | Ok b 
 
+/**
+ * Like {{`MaybeError`}} but with {{`String`}} as error type.
+ * @var The value type.
+ */
 :: MaybeErrorString a :== MaybeError String a
 
 instance Functor (MaybeError a)

src/libraries/OS-Independent/Data/Func.dcl

@@ -13,8 +13,31 @@ definition module Data.Func
  */
 app f :== f
 
+/**
+ * Apply a state function to a list of values.
+ * See also {{`mapSt`}}.
+ *
+ * @param The function.
+ * @param The list of values.
+ * @param The initial state.
+ * @result The final state.
+ */
 seqSt        :: !(a .st -> .st)       ![a] !.st -> .st
+
+/**
+ * Apply a state function to a list of values and return the results.
+ * See also {{`seqSt`}}.
+ *
+ * @param The function.
+ * @param The list of values.
+ * @param The initial state.
+ * @result The value results and the final state.
+ */
 mapSt        :: !(a .st -> (!b,!.st)) ![a] !.st -> (![b],!.st)
+
+/**
+ * The fixed point combinator, reducing `fix f` to `f (fix f)`.
+ */
 fix          :: (a -> a) -> a
 
 /**

src/libraries/OS-Independent/Data/Heap.dcl

@@ -84,18 +84,39 @@ partition :: (a -> Bool) (Heap a) -> (Heap a, Heap a)
 
 split :: a (Heap a) -> (Heap a, Heap a, Heap a)
 
+/**
+ * @type Int (Heap a) -> Heap a
+ */
 take :== withList o 'L'.take
 
+/**
+ * @type Int (Heap a) -> Heap a
+ */
 drop :== withList o 'L'.drop
 
+/**
+ * @type Int (Heap a) -> (Heap a, Heap a)
+ */
 splitAt :== splitWithList o 'L'.splitAt
 
+/**
+ * @type (a -> Bool) (Heap a) -> (Heap a, Heap a)
+ */
 break :== splitWithList o 'L'.break
 
+/**
+ * @type (a -> Bool) (Heap a) -> (Heap a, Heap a)
+ */
 span :== splitWithList o 'L'.span
 
+/**
+ * @type (a -> Bool) (Heap a) -> Heap a
+ */
 takeWhile :== withList o 'L'.takeWhile
 
+/**
+ * @type (a -> Bool) (Heap a) -> Heap a
+ */
 dropWhile :== withList o 'L'.dropWhile
 
 nub :: (Heap a) -> Heap a

src/libraries/OS-Independent/Data/Map.dcl

@@ -107,9 +107,17 @@ del :: !k !(Map k a) -> Map k a | < k
 delU :: !a !.(Map a b) -> u:(!v:(Maybe b), !Map a b) | == a & < a, [u <= v] // !k !w:(Map k u:v) -> x:(Maybe u:v, !y:(Map k u:v)) | == k & < k, [ w y <= u, x <= y, w <= y]
 
 foldrWithKey :: !(k v u:a -> u:a) !u:a !(Map k v) -> u:a
-//foldrNoKey   :: !(v u:a -> u:a) !u:a !(Map k v) -> u:a
 foldlWithKey :: !(u:a k v -> u:a) !u:a !(Map k v) -> u:a
-//foldlNoKey   :: !(a -> b -> a) !a !(Map c b) -> a
+
+/**
+ * @type (v a -> a) a (Map k v) -> a
+ */
+foldrNoKey f x m :== foldrWithKey (\_ v acc -> f v acc) x m
+
+/**
+ * @type (a v -> a) a (Map k v) -> a
+ */
+foldlNoKey f x m :== foldlWithKey (\acc _ v -> f acc v) x m
 
 /**
  * Filter elements in a Map.
@@ -218,10 +226,6 @@ mergeWithKey :: !(k a b -> Maybe c) !((Map k a) -> Map k c) !((Map k b) -> Map k
 
 foldlStrict :: !(a b -> a) !a ![b] -> a
 
-foldrNoKey f x m :== foldrWithKey (\_ v acc -> f v acc) x m
-
-foldlNoKey f x m :== foldlWithKey (\acc _ v -> f acc v) x m
-
 /**
  * Removes the values at given key positions. The mapping itself can be spine unique.
  *

src/libraries/OS-Independent/Data/Queue.dcl

 definition module Data.Queue
+
 /**
-* This module provides a straightforward FIFO queue.
-* It is implemented using two list based on Chris Okasaki's example in Purely Functional Data Structures.
-*/
+ * This module provides a straightforward FIFO queue.
+ * It is implemented using two list based on Chris Okasaki's example in Purely
+ * Functional Data Structures.
+ */
 
 from Data.Maybe import :: Maybe
 from StdOverloaded import class length
@@ -10,14 +12,14 @@ from StdOverloaded import class length
 :: Queue a = Queue [a] [a]
 
 /**
-* Create an empty queue
-*/
+ * Create an empty queue
+ */
 newQueue :: Queue a
 
 /**
-* Test if the queue is empty
-*/
-//empty :: Queue a -> Bool
+ * Test if the queue is empty
+ * @type (Queue a) -> Bool
+ */
 empty q :== case q of 
         Queue [] [] -> True
         _           -> False
@@ -25,11 +27,11 @@ empty q :== case q of
 instance length Queue
 
 /**
-* Add an element to the queue
-*/
+ * Add an element to the queue
+ */
 enqueue :: a (Queue a) -> Queue a
 
 /**
-* Take an element from the queue (if the queue is not empty)
-*/
+ * Take an element from the queue (if the queue is not empty)
+ */
 dequeue :: (Queue a) -> (!Maybe a,!Queue a)

src/libraries/OS-Independent/Data/Stack.dcl

@@ -4,20 +4,32 @@ from StdOverloaded import class length
 
 :: Stack a = Stack [a]
 
+/**
+ * Create a new, empty Stack.
+ */
 newStack :: Stack a
 
+/**
+ * Check whether a Stack is empty.
+ * @type (Stack a) -> Bool
+ */
 empty a :== case a of
 	Stack [] -> True
 	_	 -> False
 
 instance length Stack
 
-// Add element to the Stack
+/**
+ * Add an element to the Stack.
+ */
 push :: a (Stack a) -> Stack a
 
-// Remove element from the Stack and return it if the Stack is not empty
+/**
+ * Remove element from the Stack and return it if the Stack is not empty.
+ */
 pop :: (Stack a) -> (Maybe a, Stack a)
 
-// Peek the top of the Stack
+/**
+ * Peek the top of the Stack.
+ */
 peek :: (Stack a) -> Maybe a
-