Changes in documentation

1 files changed, 55 insertions, 21 deletions

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