cpukit: Doxygen group fixes and many warnings addressed

The output of the modules.html is much improved. Most
filesystem and POSIX API related groups are properly nested.
Some formatting issues were addressed as were multiple
inconsistencies.

22 files changed, 94 insertions, 89 deletions

diff --git a/cpukit/libfs/src/devfs/devfs.h b/cpukit/libfs/src/devfs/devfs.h
index 0f5e248225..fbeb13bca5 100644
--- a/cpukit/libfs/src/devfs/devfs.h
+++ b/cpukit/libfs/src/devfs/devfs.h
@@ -12,18 +12,18 @@
 
 #include <rtems/libio_.h>
 
-#ifdef __cplusplus
-extern "C" {
-#endif
 /**
- * @defgroup DevFsDeviceTable Define Device Table Type
+ * @defgroup DevFsDeviceTable Device Only File System
  *
- * @ingroup DevFs
+ * @ingroup FileSystemTypesAndMount
  *
  * @brief This structure defines the type of device table
- *
- * @{
  */
+/**@{*/
+
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 typedef struct {
   /** This member points to device name which is not a null-terminated string */
diff --git a/cpukit/libfs/src/imfs/imfs.h b/cpukit/libfs/src/imfs/imfs.h
index ba05c5baf2..6874523154 100644
--- a/cpukit/libfs/src/imfs/imfs.h
+++ b/cpukit/libfs/src/imfs/imfs.h
@@ -21,17 +21,18 @@
 #include <rtems/libio_.h>
 #include <rtems/pipe.h>
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
- * @defgroup IMFS POSIX In-Memory File System Support
- *
  * @brief In-Memory File System Support.
  *
- * @{
+ * @defgroup IMFS In-Memory File System Support
+ *
+ * @ingroup FileSystemTypesAndMount
  */
+/**@{*/
+
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 /*
  *  Data types
@@ -66,7 +67,7 @@ typedef struct {
   void *context;
 } IMFS_generic_t;
 
-/*
+/**
  *  IMFS "memfile" information
  *
  *  The data structure for the in-memory "memfiles" is based on classic UNIX.
@@ -79,14 +80,15 @@ typedef struct {
  *  memory wasted due to internal file fragmentation.  The following
  *  is a list of maximum file sizes based on various settings
  *
+ *  @code
  *    max_filesize with blocks of   16 is         1,328
  *    max_filesize with blocks of   32 is        18,656
  *    max_filesize with blocks of   64 is       279,488
  *    max_filesize with blocks of  128 is     4,329,344
  *    max_filesize with blocks of  256 is    68,173,568
  *    max_filesize with blocks of  512 is 1,082,195,456
+ *  @endcode
  */
-
 #define IMFS_MEMFILE_DEFAULT_BYTES_PER_BLOCK     128
   extern int imfs_rq_memfile_bytes_per_block;
   extern int imfs_memfile_bytes_per_block;
@@ -113,7 +115,6 @@ typedef struct {
 /*
  *  Important block numbers for "memfiles"
  */
-
 #define FIRST_INDIRECT           (0)
 #define LAST_INDIRECT            (IMFS_MEMFILE_BLOCK_SLOTS - 1)
 
@@ -134,7 +135,6 @@ typedef struct {
 /*
  *  What types of IMFS file systems entities there can be.
  */
-
 typedef enum {
   IMFS_DIRECTORY = RTEMS_FILESYSTEM_DIRECTORY,
   IMFS_DEVICE = RTEMS_FILESYSTEM_DEVICE,
@@ -165,9 +165,8 @@ typedef union {
 
 /**
  * @addtogroup IMFSGenericNodes
- *
- * @{
  */
+/**@{*/
 
 /**
  * @brief Initializes an IMFS node.
@@ -282,9 +281,8 @@ typedef struct {
 
 /**
  * @addtogroup IMFS
- *
- * @{
  */
+/**@{*/
 
 /*
  * Major device number for the IMFS. This is not a real device number because
@@ -435,32 +433,37 @@ extern void IMFS_fsunmount(
  * 
  * TAR file format:
  *
- *  Offset   Length   Contents
- *    0    100 bytes  File name ('\0' terminated, 99 maxmum length)
- *  100      8 bytes  File mode (in octal ascii)
- *  108      8 bytes  User ID (in octal ascii)
- *  116      8 bytes  Group ID (in octal ascii)
- *  124     12 bytes  File size (s) (in octal ascii)
- *  136     12 bytes  Modify time (in octal ascii)
- *  148      8 bytes  Header checksum (in octal ascii)
- *  156      1 bytes  Link flag
- *  157    100 bytes  Linkname ('\0' terminated, 99 maxmum length)
- *  257      8 bytes  Magic PAX ("ustar\0" + 2 bytes padding)
- *  257      8 bytes  Magic GNU tar ("ustar  \0")
- *  265     32 bytes  User name ('\0' terminated, 31 maxmum length)
- *  297     32 bytes  Group name ('\0' terminated, 31 maxmum length)
- *  329      8 bytes  Major device ID (in octal ascii)
- *  337      8 bytes  Minor device ID (in octal ascii)
- *  345    167 bytes  Padding
- *  512   (s+p)bytes  File contents (s+p) := (((s) + 511) & ~511),
- *                    round up to 512 bytes
+ * @code
+ *   Offset   Length                 Contents
+ *     0    100  bytes  File name ('\0' terminated, 99 maxmum length)
+ *   100      8  bytes  File mode (in octal ascii)
+ *   108      8  bytes  User ID (in octal ascii)
+ *   116      8  bytes  Group ID (in octal ascii)
+ *   124     12  bytes  File size (s) (in octal ascii)
+ *   136     12  bytes  Modify time (in octal ascii)
+ *   148      8  bytes  Header checksum (in octal ascii)
+ *   156      1  bytes  Link flag
+ *   157    100  bytes  Linkname ('\0' terminated, 99 maxmum length)
+ *   257      8  bytes  Magic PAX ("ustar\0" + 2 bytes padding)
+ *   257      8  bytes  Magic GNU tar ("ustar  \0")
+ *   265     32  bytes  User name ('\0' terminated, 31 maxmum length)
+ *   297     32  bytes  Group name ('\0' terminated, 31 maxmum length)
+ *   329      8  bytes  Major device ID (in octal ascii)
+ *   337      8  bytes  Minor device ID (in octal ascii)
+ *   345    167  bytes  Padding
+ *   512   (s+p) bytes  File contents (s+p) := (((s) + 511) & ~511),
+ *                      round up to 512 bytes
+ * @endcode
  *
  *  Checksum:
- *  int i, sum;
- *  char* header = tar_header_pointer;
- *  sum = 0;
- *  for(i = 0; i < 512; i++)
- *      sum += 0xFF & header[i];
+ *  @code
+ *    int   i, sum;
+ *    char *header = tar_header_pointer;
+ *
+ *    sum = 0;
+ *    for (i = 0; i < 512; i++)
+ *        sum += 0xFF & header[i];
+ * @endcode
  */
 extern int rtems_tarfs_load(
    const char *mountpoint,
@@ -616,9 +619,8 @@ extern bool IMFS_is_imfs_instance(
  * more features like support for fsync() and fdatasync().  The generic nodes
  * use the reference counting of the IMFS.  This provides automatic node
  * destruction when the last reference vanishes.
- *
- * @{
  */
+/**@{*/
 
 /**
  * @brief Makes a generic IMFS node.
@@ -671,9 +673,8 @@ extern int IMFS_make_generic_node(
 
 /**
  * @addtogroup IMFS
- *
- * @{
  */
+/**@{*/
 
 /**
  * @brief Mount an IMFS.
@@ -731,9 +732,8 @@ extern ssize_t imfs_dir_read(
  * malloc'ed memory.  Thus any data stored in one of these files is lost
  * at system shutdown unless special arrangements to copy the data to
  * some type of non-volailte storage are made by the application.
- * 
- * @{
  */
+/**@{*/
 
 /**
  * @brief Open a memory file.
@@ -777,9 +777,8 @@ extern ssize_t memfile_write(
  *
  * This section contains the set of handlers used to map operations on
  * IMFS device nodes onto calls to the RTEMS Classic API IO Manager.
- * 
- * @{
  */
+/**@{*/
 
 extern int device_open(
   rtems_libio_t *iop,            /* IN  */
@@ -959,9 +958,8 @@ static inline IMFS_jnode_t *IMFS_create_node(
 
 /**
  * @addtogroup IMFSGenericNodes
- *
- * @{
  */
+/**@{*/
 
 static inline void *IMFS_generic_get_context_by_node(
   const IMFS_jnode_t *node
@@ -996,11 +994,9 @@ static inline dev_t IMFS_generic_get_device_identifier_by_node(
   );
 }
 
-/** @} */
-
 #ifdef __cplusplus
 }
 #endif
-
+/** @} */
 #endif
 /* end of include file */
diff --git a/cpukit/libfs/src/pipe/pipe.h b/cpukit/libfs/src/pipe/pipe.h
index f51855c173..e9b9117f54 100644
--- a/cpukit/libfs/src/pipe/pipe.h
+++ b/cpukit/libfs/src/pipe/pipe.h
@@ -20,17 +20,18 @@
 
 #include <rtems/libio.h>
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
- * @defgroup FIFO_PIPE FIFO/pipe File System Support
+ * @defgroup FIFO_PIPE FIFO/Pipe File System Support
  *
- * @brief Interface to the POSIX FIFO/pipe File System
+ * @ingroup FileSystemTypesAndMount
  *
- * @{
+ * @brief Interface to the POSIX FIFO/Pipe File System
  */
+/**@{*/
+
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 /* Control block to manage each pipe */
 typedef struct pipe_control {
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h b/cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h
index c2497764e2..b8ed9c8d54 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File Systems Bitmap Routines
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File Systems Bitmap Routines.
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-block-pos.h b/cpukit/libfs/src/rfs/rtems-rfs-block-pos.h
index 1aab489027..3a3aab6b97 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-block-pos.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-block-pos.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File Systems Block Position and Size Management
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File Systems Block Position and Size Management.
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-block.h b/cpukit/libfs/src/rfs/rtems-rfs-block.h
index 928186f52b..ee758bafb3 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-block.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-block.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File Systems Block Management
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File Systems Block Management.
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-buffer.h b/cpukit/libfs/src/rfs/rtems-rfs-buffer.h
index ec35e648d7..40b5891a2f 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-buffer.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-buffer.h
@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * @brief Maps Blocks to the Media Interface Layers
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-data.h b/cpukit/libfs/src/rfs/rtems-rfs-data.h
index 0e20423adc..954f4bc697 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-data.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-data.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File System Data
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System Data.
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h b/cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h
index 46b2719a7e..0b2d7a40b6 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h
@@ -3,7 +3,7 @@
  *
  * @brief Provides a 32bit Hash of a String used to Search a Directory
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File Systems Directory Hash provides a 32bit hash of a string. This is
  * used to search a directory.
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-dir.h b/cpukit/libfs/src/rfs/rtems-rfs-dir.h
index ddfcb5418e..91ea713710 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-dir.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-dir.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File System Directory Support
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System Directory Support
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h b/cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h
index 19b03587e1..8010c40a16 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File Systems Data Forward Declaration
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File Systems Data forward decl.
  */
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-file-system.h b/cpukit/libfs/src/rfs/rtems-rfs-file-system.h
index 1d059ae92c..7c80aed5da 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-file-system.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-file-system.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File System Data
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System Data
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-file.h b/cpukit/libfs/src/rfs/rtems-rfs-file.h
index 9665c60ea5..efafb88e56 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-file.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-file.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File System File Support
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System File Support
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-format.h b/cpukit/libfs/src/rfs/rtems-rfs-format.h
index f0d9f0c2b1..dd2b08d2a2 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-format.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-format.h
@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * @brief RTEMS File System Format
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-group.h b/cpukit/libfs/src/rfs/rtems-rfs-group.h
index 90c6a9aa88..595a3c0886 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-group.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-group.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File Systems Group Management
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File Systems Group Management.
  *
@@ -23,11 +23,11 @@
 #define _RTEMS_RFS_GROUP_H_
 
 /**
- * @defgroup rtems-rfs FS Group Management
+ * @ingroup rtems_rfs
  *
- * @ingroup rfs
- * @{
+ * RTEMS File System Group Management
  */
+/**@{*/
 
 #include <rtems/rfs/rtems-rfs-trace.h>
 #include <rtems/rfs/rtems-rfs-bitmaps.h>
@@ -178,4 +178,4 @@ int rtems_rfs_group_usage (rtems_rfs_file_system* fs,
                            size_t*                inodes);
 
 /** @} */
-#endif
\ No newline at end of file
+#endif
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-inode.h b/cpukit/libfs/src/rfs/rtems-rfs-inode.h
index a8be80f6ff..773db4751d 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-inode.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-inode.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File System Information Node
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System Information Node.
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-link.h b/cpukit/libfs/src/rfs/rtems-rfs-link.h
index 6a1cf18f6d..c10e336d49 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-link.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-link.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File System Link Support
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System Link Support
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-mutex.h b/cpukit/libfs/src/rfs/rtems-rfs-mutex.h
index edf67f4f7b..a37d9fee72 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-mutex.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-mutex.h
@@ -3,7 +3,7 @@
  *
  * @brief RTEMS File System Mutex
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System Mutex.
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-rtems.h b/cpukit/libfs/src/rfs/rtems-rfs-rtems.h
index bbff3aeaf3..d923999f62 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-rtems.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-rtems.h
@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System RTEMS Header file.
  *
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-shell.h b/cpukit/libfs/src/rfs/rtems-rfs-shell.h
index a917b8556c..46f3d2902f 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-shell.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-shell.h
@@ -1,7 +1,7 @@
 /**
  * @file
  * 
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  * @brief RTEMS File Systems Shell Commands
  *
  * RTEMS File Systems Shell commands provide a CLI interface to support and
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-trace.h b/cpukit/libfs/src/rfs/rtems-rfs-trace.h
index 030e6c2058..7ffdea0d56 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-trace.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-trace.h
@@ -4,7 +4,7 @@
  * @brief Manages the Trace and Debugging Features of the
  * RTEMS RFS File System
  *
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File Systems Trace manages the trace and debugging features of the
  * RTEMS RFS file system. The design allows all tracing code and strings to be
diff --git a/cpukit/libfs/src/rfs/rtems-rfs.h b/cpukit/libfs/src/rfs/rtems-rfs.h
index b1684e0ebd..ffd2f806fb 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs.h
@@ -2,7 +2,7 @@
  * @file
  *
  * @brief RFS File system Initialization
- * @ingroup rtems-rfs
+ * @ingroup rtems_rfs
  *
  * RTEMS File System
  *
@@ -23,8 +23,16 @@
 #include <rtems/fs.h>
 
 /**
+ * @defgroup rtems_rfs RTEMS File System Group Management
+ *
+ * @ingroup FileSystemTypesAndMount
+ */
+/**@{*/
+
+/**
  * Initialise the RFS File system.
  */
 int rtems_rfs_rtems_initialise (rtems_filesystem_mount_table_entry_t *mt_entry);
 
+/**@}*/
 #endif