Changeset 1017 for trunk/psLib/src/collections/psList.h

Timestamp:

Jun 12, 2004, 12:15:39 PM (22 years ago)

Author:

desonia

Message:

Added addition doxygen comments.

File:

• trunk/psLib/src/collections/psList.h (modified) (3 diffs)

trunk/psLib/src/collections/psList.h

@@ -10 +10 @@
  *  @ingroup LinkedList
  *
- *  @version $Revision: 1.3 $ $Name: not supported by cvs2svn $
- *  @date $Date: 2004-06-10 01:58:06 $
+ *  @version $Revision: 1.4 $ $Name: not supported by cvs2svn $
+ *  @date $Date: 2004-06-12 22:15:39 $
  *
  *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
@@ -42 +42 @@
 typedef struct psListElem
 {
-    struct psListElem *prev;           ///< previous link in list
-    struct psListElem *next;           ///< next link in list
+    struct psListElem *prev;            ///< previous link in list
+    struct psListElem *next;            ///< next link in list
     void *data;                         ///< real data item
 }
 psListElem;
 
-/** Doubly-linked list */
+/** The psList Linked list structure.  User should not allocate this struct
+ *  directly; rather the psListAlloc should be used.
+ *
+ *  @see psListAlloc, psListFree
+ */
 typedef struct
 {
     unsigned int size;                  ///< number of elements on list
-    psListElem* head;                  ///< first element on list (may be NULL)
-    psListElem* tail;                  ///< last element on list (may be NULL)
-    psListElem* iter;                  ///< iteration cursor
+    psListElem* head;                   ///< first element on list (may be NULL)
+    psListElem* tail;                   ///< last element on list (may be NULL)
+    psListElem* iter;                   ///< iteration cursor
     unsigned int iterIndex;             ///< the numeric position of the iteration cursor in the list
     pthread_mutex_t lock;               ///< mutex to lock a node during changes
@@ -60 +64 @@
 psList;
 
-/** Constructor */
-psList *psListAlloc(
-    void *data                          ///< initial data item; may be NULL
+/** Creates a psList linked list object.
+ *
+ *  @return psList*     A new psList object.
+ */
+psList* psListAlloc(
+    void *data
+    ///< initial data item; may be NULL if no an empty psList is desired
 )
 ;
 
 #include "psMemory.h"
-/** Destructor */
+/** Destroys a psList linked list object.  This also frees the elements of the
+ *  list using the psFreeFcn given, if any.  If no psFreeFcn is specified,
+ *  the elements are just dereferenced via psMemDecrRefCounter(...).
+ *
+ */
 void psListFree(
-    psList* restrict list,             ///< list to destroy
+    psList* restrict list,              ///< list to destroy
     psFreeFcn elemFree                  ///< destructor for data on list
 );
 
-/** Add to list */
+/** Adds an element to a psList at position given.
+ *
+ *  @return psList*     The psList with added data item.  If list parameter is
+ *                      NULL, the return value will also be NULL.
+ */
 psList* psListAdd(
-    psList* restrict list,             ///< list to add to (may be NULL)
-    void* data,                         ///< data item to add
-    int where                           ///< index, PS_LIST_HEAD, or PS_LIST_TAIL
+    psList* restrict list,              ///< list to add to (if NULL, nothing is done)
+    void* data,                         ///< data item to add.  If NULL, list is not modified.
+    int where                           ///< index, PS_LIST_HEAD, PS_LIST_TAIL, or numbered location.
 );
 
-/** Append to a list */
+/** Appends an item to a psList.
+ *
+ *  @return psList*     The psList with added data item.  If list parameter is
+ *                      NULL, the return value will also be NULL.
+ */
 psList* psListAppend(
-    psList* restrict list,             ///< list to append to (may be NULL)
-    void *data                          ///< data item to add
+    psList* restrict list,              ///< list to append to (if NULL, nothing is done)
+    void *data                          ///< data item to add. If NULL, list is not modified.
 );
 
-/** Remove from a list */
+/** Remove an item from a list.  If which parameter is PS_LIST_UNKNOWN,
+ *
+ *  @return void*       The data item that was removed.  If NULL, no item was
+ *                      removed.
+ */
 void* psListRemove(
-    psList* restrict list,             ///< list to remove element from
-    void *data,                         ///< data item to remove
-    int which                           ///< index of item, or PS_LIST_UNKNOWN, PS_LIST_NEXT, PS_LIST_PREV
+    psList* restrict list,
+    ///< list to remove element from
+    void *data,
+    ///< if which is PS_LIST_UNKNOWN, data item to find and remove, otherwise this is ignored.
+    int which
+    ///< index of item, or PS_LIST_UNKNOWN, PS_LIST_NEXT, PS_LIST_PREV, or numbered location.
 );
 
-/** Retrieve from a list */
+/** Retrieve an item from a list.
+ *
+ *  @return void*       the item corresponding to the which parameter.  If
+ *                      which is invalid (e.g., a numbered index greater
+ *                      than the list size or if the list is empty), a
+ *                      NULL is returned.
+ */
 void* psListGet(
     psList* restrict list,             ///< list to retrieve element from
-    int which                           ///< index of item, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN
+    int which                          ///< index number, or PS_LIST_NEXT, PS_LIST_PREV, PS_LIST_UNKNOWN
 );
 
-/** Set the iterator */
+/** Set the iterator of the list to a given position.  If where is invalid the
+ *  iterator position is not changed.
+ *
+ */
 void psListSetIterator(
     psList* restrict list,             ///< list to retrieve element from
-    int where                           ///< index, PS_LIST_HEAD, or PS_LIST_TAIL
+    int where                           ///< index number, PS_LIST_HEAD, or PS_LIST_TAIL
 );
 
-/** Get next element relative to iter */
+/** Get next element relative to the iterator.  This also moves the iterator to
+ *  the next list position.
+ *
+ *  @return void*       the data item next on the list or NULL if the iterator
+ *                      is already pointing to the last element or the list
+ *                      parameter was NULL.
+ */
 void* psListGetNext(
     psList* restrict list              ///< list to retrieve element from
 );
 
-/** Get current element at iter */
+/** Get current element according to the psList's iterator cursor.  This does
+ *  not move the iterator location.
+ *
+ *  @return void*       the data item cooresponding to current iterator
+ *                      cursor position of the list, or NULL if either the
+ *                      iterator is not valid or list parameter was NULL.
+ */
 void* psListGetCurrent(
     psList* restrict list              ///< list to retrieve element from
 );
 
-/** Get prev element relative to iter */
+/** Get previous element relative to list's iterator. This also moves the
+ *  iterator to the previous list position.
+ *
+ *  @return void*       the data item previous on the list or NULL if the iterator
+ *                      is already pointing to the first element or the list
+ *                      parameter was NULL.
+ */
 void* psListGetPrevious(
     psList* restrict list              ///< list to retrieve element from
 );
 
-/** Convert doubly-linked list to an array */
+/** Convert a linked list to an array
+ *
+ *  @return psVector*   A new psVector populated with elements from the list,
+ *                      or NULL if the given dlist parameter is NULL.
+ */
 psVector* psListToVector(
     psList *dlist                      ///< List to convert
 );
 
-/** Convert array to a doubly-linked list */
+/** Convert array to a doubly-linked list
+ *
+ *  @return psList*     A new psList populated with elements formt the psVector,
+ *                      or NULL is the given arr parameter is NULL.
+ */
 psList* psVectorToList(
-    psVector* arr                       ///< vector to convert
+    psVector* arr                      ///< vector to convert
 );