Changes in documentation

2 files changed, 211 insertions, 28 deletions

diff --git a/utils/DList.cc b/utils/DList.cc
index 96a2db8..711a32c 100644
--- a/utils/DList.cc
+++ b/utils/DList.cc
@@ -430,13 +430,14 @@ CcuDList :: RemoveAfter (const CcuDListIter& li)
 Remove the element pointed at by the iterator \var{li}.
 If \var{li} points before the beginning of the list, or has reached
 its end, the return value is null, and the status flag is set to \var{TooEarly}
-{resp. \var{TooFar}). In all other cases, \var{li} is rewinded by one step,
+(resp. \var{TooFar}). In all other cases, \var{li} is rewinded by one step,
 in order to allow such loops as:
+\begin{ccode}
     CcuDListIter li (l);
-    while (++li) {
+    while (++li)
         if (do_remove (*li))
             l.RemoveAt (l);
-    }
+\end{ccode}
 ?*/
 CcuDListItem*
 CcuDList :: RemoveAt (CcuDListIter& li)
@@ -461,11 +462,17 @@ CcuDList :: RemoveAt (CcuDListIter& li)
 
 
 #ifdef DOC
+/*?class CcuDListIter
+The class \typ{CcuDListIter} allows iterations on lists.
+Several iterators may be used at a time on the same list. It is dangerous to modify
+a list that is being iterated.
+?*/
+
 /*?
 Initialize an iterator associated to the list \var{l}. That iterator will point at the beginning
 of the list, {\em before} the first element.
 ?*/
-CcuDListIter :: CcuDListIter (CcuDList& l)
+CcuDListIter :: CcuDListIter (const CcuDList& l)
 {
 }
 
@@ -478,14 +485,20 @@ CcuDListIter :: GetStatus () const
 {
 }
 
+/*?nextdoc?*/
+void
+CcuDListIter :: Reset ()
+{
+}
+
 /*?
-Reset an iterator to the beginning of the list.
+Reset an iterator to the beginning (resp. the end) of the list.
 ?*/
 void
-CcuDListIter :: Reset ()
+CcuDListIter :: GotoEnd ()
 {
 }
-#endif
+#endif	/* DOC */
 
 
 /*?
@@ -575,3 +588,139 @@ CcuDListIter :: FindBack (CcuDListItem* e)
 	return 0;
 }
 
+#ifdef DOC
+
+/*?class CcuDListOf
+The generic classes \typ{CcuDListOf} and \typ{CcuDListIterOf} are derived classes
+of \typ{CcuDList} and \typ{CcuDListIter} that provide lists of pointers to class objects.
+When parameterized by the class \typ{ITEM}, the following functions are redefined:
+?*/
+
+/*?nextdoc?*/
+CcuDListOf :: CcuDListOf (ITEM* it)
+{
+}
+
+/*?nextdoc?*/
+ITEM*
+CcuDListOf :: First ()
+{
+}
+
+/*?nextdoc?*/
+ITEM*
+CcuDListOf :: Last ()
+{
+}
+
+/*?nextdoc?*/
+ITEM*
+CcuDListOf :: Nth (int n)
+{
+}
+
+/*?nextdoc?*/
+int
+CcuDListOf :: Find (ITEM* it) const
+{
+}
+
+/*?nextdoc?*/
+void
+CcuDListOf :: Append (ITEM* it)
+{
+}
+
+/*?nextdoc?*/
+void
+CcuDListOf :: Prepend (ITEM* it)
+{
+}
+
+/*?nextdoc?*/
+CcuDListOf&
+CcuDListOf :: operator << (ITEM* it)
+{
+}
+
+/*?nextdoc?*/
+ITEM*
+CcuDListOf :: RemoveFirst ()
+{
+}
+
+/*?nextdoc?*/
+ITEM*
+CcuDListOf :: RemoveLast ()
+{
+}
+
+/*?nextdoc?*/
+int
+CcuDListOf :: Remove (ITEM* it, int nb = 1)
+{
+}
+
+/*?nextdoc?*/
+int
+CcuDListOf :: Remove (int (*p) (ITEM*), int nb = 1)
+{
+}
+
+/*?nextdoc?*/
+void
+CcuDListOf :: InsertAfter (const CcuDListIterOf <ITEM>& li, ITEM*it)
+{
+}
+
+/*?nextdoc?*/
+void
+CcuDListOf :: InsertBefore (const CcuDListIterOf <ITEM>& li, ITEM* it)
+{
+}
+
+/*?nextdoc?*/
+ITEM*
+CcuDListOf :: RemoveAfter (const CcuDListIterOf <ITEM>& li)	
+{
+}
+
+/*?
+These functions are equivalent to their homonyms in the class \typ{CcuDList},
+except that they are customized in order to manipulate pointers to \typ{ITEM}
+instead of \typ{void*}.
+?*/
+ITEM*
+CcuDListOf :: RemoveAt (CcuDListIterOf <ITEM>& li)	
+{
+}
+
+/*?nextdoc?*/
+CcuDListIterOf  :: CcuDListIterOf (const CcuDListOf <ITEM>& l)
+{
+}
+	
+/*?nextdoc?*/
+ITEM*
+CcuDListIterOf :: operator * () const
+{
+}
+
+/*?nextdoc?*/
+int
+CcuDListIterOf :: Find (ITEM* it)	
+{
+}
+
+/*?
+These functions are equivalent to their homonyms in the class \typ{CcuDListIter},
+except that they are customized in order to manipulate pointers to \typ{ITEM}
+instead of \typ{void*}.
+?*/
+int
+CcuDListIterOf :: FindBack (ITEM* it)	
+{
+}
+
+
+#endif	/* DOC */
diff --git a/utils/List.cc b/utils/List.cc
index cbac66f..dd07956 100644
--- a/utils/List.cc
+++ b/utils/List.cc
@@ -166,6 +166,17 @@ CcuList :: operator = (const CcuList& l)
 	return *this;
 }
 
+#ifdef DOC
+/*?
+Get the status flag of a list. This can be one of \var{NoError, WasEmpty, TooEarly, TooFar} or
+\var{BadIterator}. The status flag is modified by most operations on lists. Those which
+modify it when errors are encountered also set it to \var{NoError} when there is no error.
+?*/
+list_status
+CcuList :: GetStatus () const
+{
+}
+#endif	/* DOC */
 
 /*?nextdoc?*/
 CcuListItem*
@@ -182,7 +193,8 @@ CcuList :: First ()
 /*?
 Return the first (resp. last) element in the list, or 0 if the list was empty.
 The case of a null element can be distinguished from the case
-when the list is empty with the function \fun{GetStatus}.
+when the list is empty with the function \fun{GetStatus}: the status flag is
+set to \var{WasEmpty} in the latter case.
 ?*/
 CcuListItem*
 CcuList :: Last ()
@@ -264,7 +276,8 @@ CcuList :: Append (CcuListItem* e)
 }
 
 /*?
-Remove the first element of a list and return it.
+Remove the first element of a list and return it. The status flag is set to
+\var{WasEmpty} when the list was empty.
 ?*/
 CcuListItem*
 CcuList :: RemoveFirst ()
@@ -292,7 +305,8 @@ CcuList :: RemoveFirst ()
 
 
 /*?
-Remove the last element of a list and return it. This function has to locate the last
+Remove the last element of a list and return it. The status flag is set to
+\var{WasEmpty} when the list was empty. This function has to locate the last
 element, and hence has a linear cost.
 ?*/
 CcuListItem*
@@ -442,7 +456,8 @@ Insert an element before (resp. after) the current position of the iterator \var
 These functions are both equivalent to \fun{CcuList::Prepend} if the iterator is at the 
 beginning of the list (ie. before the first element).
 \fun{InsertAfter} is performed in a constant time, while \fun{InsertBefore}
-has a linear cost.
+has a linear cost. If \var{li} is not an iterator on this list, the status flag of the list
+is set to \var{BadIterator}.
 ?*/
 void
 CcuList :: InsertBefore (const CcuListIter& li, CcuListItem* e)
@@ -468,20 +483,24 @@ CcuList :: InsertBefore (const CcuListIter& li, CcuListItem* e)
 
 /*?
 Remove the element after the current element of the iterator \var{li}.
-If \var{li} points before the beginning of the list, the first element is returned.
+If \var{li} points before the beginning of the list, the first element is removed.
 If \var{li} points at the last element, the status flag is set to \var{TooFar}.
 If the list is empty, the flag is set to \var{EmptyList}. In both cases, the 
-return value is null.
+return value is null. If \var{li} is not an iterator
+on this list, the flag is set to \var{BadIterator}. 
 This function may be used
 when one wants to iterate through a list and remove some elements:
-    CcuListIter li (l);
-    CcuListIter lj (l);
+\begin{ccode}
+    CcuListIter li = l;
+    CcuListIter lj = l;
     while (++li)
         if (do_remove (*li)) {
-        	RemoveAfter (lj);
-        	li = lj;
-        } else
-        	++lj;
+            l.RemoveAfter (lj);
+            li = lj;
+        } else {
+            ++lj;
+        }
+\end{ccode}
 ?*/
 CcuListItem*
 CcuList :: RemoveAfter (const CcuListIter& li)
@@ -505,11 +524,27 @@ CcuList :: RemoveAfter (const CcuListIter& li)
 
 #ifdef DOC
 
+/*?class CcuListIter
+The class \typ{CcuListIter} allows iterations on lists.
+Several iterators may be used at a time on the same list. It is dangerous to modify
+a list that is being iterated. Refer to the implementation figure for more details.
+Of course, the functions such as \var{InsertAfter} or \var{RemoveAfter} are designed
+to be harmless. However, they may be dangerous if another iterator is used at the same
+time on the same list.
+The basic usage of an iterator is the following:
+\begin{ccode}
+    extern CcuList& l;
+    CcuListIter li = l;
+    while (++li)
+        foo (*li);    // *li is the value that was stored with Append
+\end{ccode}
+?*/
+
 /*?
 Initialize an iterator associated to the list \var{l}. That iterator will point at the beginning
 of the list, {\em before} the first element.
 ?*/
-CcuListIter :: CcuListIter (CcuList& l)
+CcuListIter :: CcuListIter (const CcuList& l)
 {
 }
 
@@ -576,8 +611,7 @@ CcuListIter :: operator ++ ()
 #ifndef CPLUS_BUG16
 /*?
 Post-increment equivalent of the previous operator. This operator is just here
-as a demonstrator: it was not tested because no known compiler implements that feature,
-and its semantics is quite muddy.
+as a placeholder: it does the same thing as the previous one.
 ?*/
 CcuListIter&
 CcuListIter :: operator ++ (int)
@@ -687,17 +721,17 @@ CcuListOf :: InsertAfter (const CcuListIterOf <ITEM>& li, ITEM*it)
 {
 }
 
-/*?
-These functions are equivalent to their homonyms in the class \typ{CcuList},
-except that they are customized in order to manipulate pointers to \typ{ITEM}
-instead of \typ{void*}.
-?*/
+/*?nextdoc?*/
 void
 CcuListOf :: InsertBefore (const CcuListIterOf <ITEM>& li, ITEM* it)
 {
 }
 
-/*?nextdoc?*/
+/*?
+These functions are equivalent to their homonyms in the class \typ{CcuList},
+except that they are customized in order to manipulate pointers to \typ{ITEM}
+instead of \typ{void*}.
+?*/
 ITEM*
 CcuListOf :: RemoveAfter (const CcuListIterOf <ITEM>& li)	
 {