with doxygen, some of the stuff in low.doc is redundant, and what is not is...

with doxygen, some of the stuff in low.doc is redundant, and what is not is better placed directly in the code

[[Imported from SVN: r8154]]

low/low.doc

@@ -35,34 +35,6 @@
 D*/
 /***************************************************************************/
 
-/****************************************************************************/
-/*D
-   fifo - Functions to handle a fifo (first in, first out) structure.
-
-   DESCRIPTION:
-   These functions support the handling of a fifo (first in, first out stack) structure.
-   
-	The file 'fifo.c' supplies the functions
-
-.vb
-   fifo_init    (FIFO  *myfifo, void *buffer, INT size)
-   
-   fifo_clear   (FIFO  *myfifo)
-   
-   fifo_empty   (const FIFO *myfifo)
-   
-   fifo_full    (const FIFO *myfifo)
-   
-   fifo_in      (FIFO *myfifo, void *newelement)
-   
-   *fifo_out    (FIFO *myfifo)   
-.ve
-   For a  detailed description see the manual pages of each function.
-
-   SEE ALSO:
-   fifo_init, fifo_clear, fifo_empty, fifo_full, fifo_in, fifo_out
-D*/
-/****************************************************************************/
 
 /****************************************************************************/
 /*D
@@ -224,82 +196,3 @@ typedef struct {                // directory
 D*/
 /****************************************************************************/
 
-/***************************************************************************/
-/*D
-    ENVITEM - data structure for objects in the environment tree
-    
-    DEFINITION:
-.vb
-union envitem {
-    ENVVAR v;
-    ENVDIR d;
-};
-
-typedef union envitem ENVITEM;
-
-typedef struct {                // user defined variable                    
-    INT type;                   // one of the variable types above          
-    INT locked;                 // may not be changed or deleted            
-    union envitem *next;
-    union envitem *previous;    // double linked list of environment items  
-    char name[NAMESIZE];        // name of that item                        
-                                // may be longer, but of no interest for env
-} ENVVAR;
-
-typedef struct {                // directory                                
-    INT type;                   // one of the directory types above         
-    INT locked;                 // may not be changed or deleted            
-    union envitem *next;
-    union envitem *previous;    // double linked list of environment items  
-    char name[NAMESIZE];        // name of that item                        
-    union envitem *down;        // one level down in the tree               
-} ENVDIR;
-.ve
-
-    DEFINES:
-.   NAMESIZE    - the size of the name strings of environment items
-.   NAMELEN     - maximal length of the name strings (NAMELEN-1)
-.   NAMELENSTR  - 'NAMELEN' as string "'NAMELEN'"
-.   SEARCHALL   - argument for 'SearchEnv'
-.   DIRSEP      - the directory seperator character
-    
-    MACROS:
-.vb
-ENVITEM *ENVITEM_DOWN   (ENVDIR *d)
-.ve
-Return pointer to the first 'ENVITEM' contained in the directory.
-
-.vb
-ENVITEM *ENVDIR_DOWN    (ENVDIR *d)
-.ve
-Return pointer to the first 'ENVITEM' contained in the directory.
-
-.vb
-ENVITEM *NEXT_ENVITEM   (ENVITEM *p)
-.ve
-Return pointer to the next 'ENVITEM' in the doubly linked list.
-
-.vb
-ENVITEM *PREV_ENVITEM   (ENVITEM *p)
-.ve
-Return pointer to the previous 'ENVITEM' in the doubly linked list.
-
-.vb
-INT      ENVITEM_TYPE   (ENVITEM *p)
-.ve
-Return the type of the 'ENVITEM' (odd: 'ENVDIR', even: 'ENVVAR').
-
-.vb
-INT      ENVITEM_LOCKED (ENVITEM *p)
-.ve
-'RemoveEnvItem' checks this and returns an error if TRUE.
-
-.vb
-char    *ENVITEM_NAME   (ENVITEM *p)
-.ve
-This macro returns a pointer to the name string of the 'ENVITEM'.
-
-    SEE ALSO:
-    ugenv
-D*/
-/****************************************************************************/

low/ugenv.h

@@ -59,13 +59,27 @@ enum {NAMELEN  = 127};                 /* NAMESIZE-1
 /* directories with odd numbers */
 #define ROOT_DIR            1        /* indicates root directory             */
 
+/** \brief Return pointer to the first 'ENVITEM' contained in the directory. */
 #define ENVITEM_DOWN(p)         (((ENVITEM *)(p))->d.down)
+
+/** \brief Return pointer to the first 'ENVDIR' contained in the directory. */
 #define ENVDIR_DOWN(p)            ((p)->down)
+
+/** \brief Return pointer to the next 'ENVITEM' in the doubly linked list */
 #define NEXT_ENVITEM(p)         (((ENVITEM *)(p))->v.next)
+
+/** \brief Return pointer to the previous 'ENVITEM' in the doubly linked list. */
 #define PREV_ENVITEM(p)         (((ENVITEM *)(p))->v.previous)
+
+/** \brief Return the type of the 'ENVITEM' (odd: 'ENVDIR', even: 'ENVVAR'). */
 #define ENVITEM_TYPE(p)         (((ENVITEM *)(p))->v.type)
+
 #define IS_ENVDIR(p)            (ENVITEM_TYPE(p)%2==1)
+
+/** \brief This macro returns a pointer to the name string of the 'ENVITEM'. */
 #define ENVITEM_NAME(p)         (((ENVITEM *)(p))->v.name)
+
+/** \brief 'RemoveEnvItem' checks this and returns an error if TRUE. */
 #define ENVITEM_LOCKED(p)         (((ENVITEM *)(p))->v.locked)
 
 /****************************************************************************/