libfs: Doxygen Clean Up Task #2

There were minor conflicts and the modifications that were
in the repo were favored over the modifications in the submitted
patch.

9 files changed, 195 insertions, 94 deletions

diff --git a/cpukit/libfs/src/dosfs/dosfs.h b/cpukit/libfs/src/dosfs/dosfs.h
index 2374e63f2b..79560bb373 100644
--- a/cpukit/libfs/src/dosfs/dosfs.h
+++ b/cpukit/libfs/src/dosfs/dosfs.h
@@ -1,7 +1,9 @@
 /**
- *  @file rtems/dosfs.h
+ * @file rtems/dosfs.h
  *
- *  Application interface to MSDOS filesystem.
+ * @brief Application Interface to MSDOS Filesystem
+ *
+ * @ingroup rtems_msdos_format
  */
 
 /*
diff --git a/cpukit/libfs/src/dosfs/fat.h b/cpukit/libfs/src/dosfs/fat.h
index 5d36fb45c0..ace236b50e 100644
--- a/cpukit/libfs/src/dosfs/fat.h
+++ b/cpukit/libfs/src/dosfs/fat.h
@@ -1,8 +1,15 @@
-/*
- *  fat.h
+/**
+ * @file
+ *
+ * @brief Constants/Data Structures/Prototypes on a Volume with FAT Filesystem
  *
- *  Constants/data structures/prototypes for low-level operations on a volume
- *  with FAT filesystem
+ * @ingroup libfs_dosfs
+ *
+ * Constants/Data Structures/Prototypes for Low-Level
+ * Operations on a Volume with FAT Filesystem
+ */
+
+/*
  *
  *  Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
  *  Author: Eugeny S. Mints <Eugeny.Mints@oktet.ru>
@@ -23,6 +30,12 @@
 #include <errno.h>
 #include <rtems/bdbuf.h>
 
+/**
+ *  @defgroup libfs_dosfs FAT FileSystem
+ *
+ *  @ingroup libfs
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -545,5 +558,5 @@ fat_sync(fat_fs_info_t *fs_info);
 #ifdef __cplusplus
 }
 #endif
-
-#endif /* __DOSFS_FAT_H__ */
+/**@}*/
+#endif /* __DOSFS_FAT_H__ */
\ No newline at end of file
diff --git a/cpukit/libfs/src/dosfs/fat_fat_operations.h b/cpukit/libfs/src/dosfs/fat_fat_operations.h
index 278947ffca..69589153d2 100644
--- a/cpukit/libfs/src/dosfs/fat_fat_operations.h
+++ b/cpukit/libfs/src/dosfs/fat_fat_operations.h
@@ -1,9 +1,15 @@
-/*
- *  fat_fat_operations.h
+/**
+ * @file
  *
- *  Constants/data structures/prototypes for operations on Files Allocation
- *  Table
+ * @brief Constants/Data Structures/Prototypes for Files Allocation Table
  *
+ * @ingroup libfs_ffo
+ *
+ * Constants/Data Structures/Prototypes for
+ * Operations on Files Allocation Table
+ */
+
+/*
  *  Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
  *  Author: Eugeny S. Mints <Eugeny.Mints@oktet.ru>
  *
@@ -11,6 +17,7 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
+
 #ifndef __DOSFS_FAT_FAT_OPERATIONS_H__
 #define __DOSFS_FAT_FAT_OPERATIONS_H__
 
diff --git a/cpukit/libfs/src/dosfs/fat_file.h b/cpukit/libfs/src/dosfs/fat_file.h
index 0e22c90e60..d9753a9d5b 100644
--- a/cpukit/libfs/src/dosfs/fat_file.h
+++ b/cpukit/libfs/src/dosfs/fat_file.h
@@ -1,7 +1,12 @@
-/*
- *  fat_file.h
+/**
+ * @file
  *
- *  Constants/data structures/prototypes for operations on "fat-file"
+ * @brief Constants/Data Structures/Prototypes for Operations on "fat-file"
+ *
+ * @ingroup libfs_ff
+ */
+
+/*
  *
  *  Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
  *  Author: Eugeny S. Mints <Eugeny.Mints@oktet.ru>
@@ -10,6 +15,7 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
+
 #ifndef __DOSFS_FAT_FILE_H__
 #define __DOSFS_FAT_FILE_H__
 
@@ -26,11 +32,13 @@
  *  @ingroup libfs
  */
 /**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* "fat-file" representation
+/**
+ * @brief The "fat-file" representation.
  *
  * the idea is: fat-file is nothing but a cluster chain, any open fat-file is
  * represented in system by fat-file descriptor and has well-known
@@ -44,7 +52,6 @@ extern "C" {
  * Such interface hides the architecture of fat-file and represents it like
  * linear file
  */
-
 typedef rtems_filesystem_node_types_t fat_file_type_t;
 
 #define FAT_DIRECTORY     RTEMS_FILESYSTEM_DIRECTORY
@@ -56,8 +63,9 @@ typedef struct fat_file_map_s
     uint32_t   disk_cln;
     uint32_t   last_cln;
 } fat_file_map_t;
-/*
- * descriptor of a fat-file
+
+/**
+ * @brief Descriptor of a fat-file.
  *
  * To each particular clusters chain
  */
@@ -109,18 +117,17 @@ typedef struct fat_file_fd_s
 
 #define FAT_EOF           0x00
 
-/* fat_construct_key --
- *     Construct key for hash access: convert (cluster num, offset) to
- *     (sector512 num, new offset) and than construct key as
- *     key = (sector512 num) << 4 | (new offset)
+/* @brief Construct key for hash access.
+ *
+ * Construct key for hash access: convert (cluster num, offset) to
+ * (sector512 num, new offset) and than construct key as
+ * key = (sector512 num) << 4 | (new offset)
  *
- * PARAMETERS:
- *     cl       - cluster number
- *     ofs      - offset inside cluster 'cl'
- *     fs_info  - FS info
+ * @param[in] cl - cluster number
+ * @param[in] ofs - offset inside cluster 'cl'
+ * @param[in] fs_info - FS info
  *
- * RETURNS:
- *     constructed key
+ * @retval constructed key
  */
 static inline uint32_t
 fat_construct_key(
@@ -189,4 +196,4 @@ fat_file_mark_removed(fat_fs_info_t                        *fs_info,
 }
 #endif
 /**@}*/
-#endif /* __DOSFS_FAT_FILE_H__ */
+#endif /* __DOSFS_FAT_FILE_H__ */
\ No newline at end of file
diff --git a/cpukit/libfs/src/dosfs/msdos.h b/cpukit/libfs/src/dosfs/msdos.h
index d4f674317f..9465d268d7 100644
--- a/cpukit/libfs/src/dosfs/msdos.h
+++ b/cpukit/libfs/src/dosfs/msdos.h
@@ -1,8 +1,12 @@
-/*
- *  msdos.h
+/**
+ * @file
  *
- *  The MSDOS filesystem constants/data structures/prototypes
+ * @brief The MSDOS Filesystem Constants/Data Structures/Prototypes
  *
+ * @ingroup libfs_msdos
+ */
+
+/*
  *  Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
  *  Author: Eugeny S. Mints <Eugeny.Mints@oktet.ru>
  *
@@ -10,6 +14,7 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
+
 #ifndef __DOSFS_MSDOS_H__
 #define __DOSFS_MSDOS_H__
 
@@ -276,7 +281,7 @@ int msdos_rmnod(
 );
 
 /**
- * @brief rename a MSDOS filesystem node
+ * @brief Rename a MSDOS filesystem node.
  *
  * Routine to rename a MSDOS filesystem node
  */
@@ -293,7 +298,7 @@ void msdos_lock(const rtems_filesystem_mount_table_entry_t *mt_entry);
 void msdos_unlock(const rtems_filesystem_mount_table_entry_t *mt_entry);
 
 /**
- *  @brief The MSDOS filesystem initialization.
+ *  @brief MSDOS filesystem initialization routine.
  *
  *  MSDOS Initialization support routine implementation
  */
diff --git a/cpukit/libfs/src/nfsclient/proto/mount_prot.h b/cpukit/libfs/src/nfsclient/proto/mount_prot.h
index e74a3cd688..a5cac29217 100644
--- a/cpukit/libfs/src/nfsclient/proto/mount_prot.h
+++ b/cpukit/libfs/src/nfsclient/proto/mount_prot.h
@@ -1,6 +1,9 @@
-/*
- * Please do not edit this file.
- * It was generated using rpcgen.
+/**
+ * @file
+ *
+ * @brief Nfsclient Mount Prot
+ *
+ * @ingroup rtems-nfsclient
  */
 
 #ifndef _MOUNT_PROT_H_RPCGEN
diff --git a/cpukit/libfs/src/nfsclient/src/librtemsNfs.h b/cpukit/libfs/src/nfsclient/src/librtemsNfs.h
index fc4802874a..ddef9eeab9 100644
--- a/cpukit/libfs/src/nfsclient/src/librtemsNfs.h
+++ b/cpukit/libfs/src/nfsclient/src/librtemsNfs.h
@@ -1,11 +1,14 @@
-#ifndef LIB_RTEMS_NFS_CLIENT_H
-#define LIB_RTEMS_NFS_CLIENT_H
-
-/* public interface to the NFS client library for RTEMS */
-
-/* Author: Till Straumann <strauman@slac.stanford.edu> 2002-2003 */
+/**
+ * @file
+ *
+ * @brief Public Interface to the NFS Client Library for RTEMS
+ *
+ * @ingroup rtems-nfsclient
+ */
 
 /*
+ * Author: Till Straumann <strauman@slac.stanford.edu> 2002-2003
+ *
  * Authorship
  * ----------
  * This software (NFS-2 client implementation for RTEMS) was created by
@@ -50,6 +53,16 @@
  * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
  */
 
+#ifndef LIB_RTEMS_NFS_CLIENT_H
+#define LIB_RTEMS_NFS_CLIENT_H
+
+/**
+ * @defgroup rtems-nfsclient NFS Client Library
+ *
+ * @ingroup nfsclient
+ * @{
+ */
+
 #ifdef	HAVE_CONFIG_H
 #include <config.h>
 #endif
@@ -73,40 +86,41 @@
 extern "C" {
 #endif
 
-/* RPCIO driver interface.
+/** RPCIO driver interface.
  * If you need RPCIO for other purposes than NFS
  * you may want to include <rpcio.h>
 #include "rpcio.h"
  */
 
-/* Priority of daemon; may be setup prior to calling rpcUdpInit();
+/** Priority of daemon; may be setup prior to calling rpcUdpInit();
  * otherwise the network task priority from the rtems_bsdnet_config
  * is used...
  */
 extern rtems_task_priority rpciodPriority;
 
-/* Initialize the driver.
+/** Initialize the driver.
  *
  * Note, called in nfsfs initialise when mount is called.
  *
- * RETURNS: 0 on success, -1 on failure
+ * @retval 0 on success, -1 on failure
  */
 int
 rpcUdpInit(void);
 
-/* Cleanup/Stop
+/**
+ * @brief RPC cleanup and stop.
  *
- * RETURNS: 0 on success, nonzero if still in use
+ * @retval 0 on success, nonzero if still in use
  */
 int
 rpcUdpCleanup(void);
 
-/* NFS driver interface */
+/** NFS driver interface */
 
-/* Initialize the NFS driver.
+/**
+ * @brief Initialize the NFS driver.
  *
- * NOTE: The RPCIO driver must have been initialized prior to
- *       calling this.
+ * The RPCIO driver must have been initialized prior to calling this.
  *
  * Note, called in nfsfs initialise when mount is called with defaults.
  *
@@ -125,50 +139,60 @@ rpcUdpCleanup(void);
 void
 nfsInit(int smallPoolDepth, int bigPoolDepth);
 
-/* Driver cleanup code
+/**
+ * @brief Driver cleanup code.
  *
- * RETURNS: 0 on success, nonzero if still in use
+ * @retval 0 on success, nonzero if still in use
  */
 int
 nfsCleanup(void);
 
-/* Dump a list of the currently mounted NFS to a file
+/**
+ * @brief Dump a list of the currently mounted NFS to a file.
+ *
+ * Dump a list of the currently mounted NFS to a file
  * (stdout is used in case f==NULL)
  */
 int
 nfsMountsShow(FILE *f);
 
-/*
+/**
+ * @brief Filesystem mount table mount handler.
+ *
  * Filesystem mount table mount handler. Do not call, use the mount call.
  */
-int 
+int
 rtems_nfs_initialize(rtems_filesystem_mount_table_entry_t *mt_entry,
                      const void                           *data);
 
-/* A utility routine to find the path leading to a
+/**
+ * @brief A utility routine to find the path leading to a
  * rtems_filesystem_location_info_t node.
  *
  * This should really be present in libcsupport...
  *
- * INPUT: 'loc' and a buffer 'buf' (length 'len') to hold the
- *        path.
- * OUTPUT: path copied into 'buf'
+ * @param[in] 'loc' and a buffer 'buf' (length 'len') to hold the path.
+ *
+ * @param[out] path copied into 'buf'
  *
- * RETURNS: 0 on success, RTEMS error code on error.
+ * @retval 0 on success, RTEMS error code on error.
  */
 rtems_status_code
 rtems_filesystem_resolve_location(char *buf, int len, rtems_filesystem_location_info_t *loc);
 
-/* Set the timeout (initial default: 10s) for NFS and mount calls.
+/**
+ * @brief Set the timeout (initial default: 10s) for NFS and mount calls.
  *
- * RETURNS 0 on success, nonzero if the requested timeout is less than
+ * Set the timeout (initial default: 10s) for NFS and mount calls.
+ *
+ * @retval 0 on success, nonzero if the requested timeout is less than
  * a clock tick or if the system clock rate cannot be determined.
  */
 
 int
 nfsSetTimeout(uint32_t timeout_ms);
 
-/* Read current timeout (in milliseconds) */
+/** Read current timeout (in milliseconds) */
 uint32_t
 nfsGetTimeout(void);
 
@@ -176,4 +200,5 @@ nfsGetTimeout(void);
 }
 #endif
 
-#endif
+/** @} */
+#endif
\ No newline at end of file
diff --git a/cpukit/libfs/src/nfsclient/src/rpcio.h b/cpukit/libfs/src/nfsclient/src/rpcio.h
index 8078209610..02cd34ffe7 100644
--- a/cpukit/libfs/src/nfsclient/src/rpcio.h
+++ b/cpukit/libfs/src/nfsclient/src/rpcio.h
@@ -1,11 +1,14 @@
-#ifndef RPCIO_H
-#define RPCIO_H
-
-/* A multihreaded RPC/UDP multiplexor */
-
-/* Author: Till Straumann, <strauman@slac.stanford.edu>, 2002 */
+/**
+ * @file
+ *
+ * @brief A Multithreaded RPC/UDP Multiplexor
+ *
+ * @ingroup rtems-nfsclient
+ */
 
 /*
+ * Author: Till Straumann, <strauman@slac.stanford.edu>, 2002
+ *
  * Authorship
  * ----------
  * This software (NFS-2 client implementation for RTEMS) was created by
@@ -50,6 +53,16 @@
  * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
  */
 
+#ifndef RPCIO_H
+#define RPCIO_H
+
+/**
+ * @defgroup rtems-nfsclient RPC/UDP Multiplexor
+ *
+ * @ingroup nfsclient
+ * @{
+ */
+
 #ifdef __rtems
 #include <rtems.h>
 #endif
@@ -84,8 +97,9 @@ rpcUdpServerCreate(
 void
 rpcUdpServerDestroy(RpcUdpServer s);
 
-/* Dump statistics to a file (stdout if NULL);
- * returns 0 for convenience
+/**
+ * @brief Dump statistics to a file (stdout if NULL);
+ * @retval 0 for convenience
  */
 int
 rpcUdpStats(FILE *f);
@@ -103,7 +117,9 @@ rpcUdpClntCreate(
 void
 RpcUdpClntDestroy(RpcUdpClnt clnt);
 
-/* mute compiler warnings */
+/**
+ * @brief Mute compiler warnings.
+ */
 typedef void *XdrProcT;
 typedef void *CaddrT;
 
@@ -130,7 +146,9 @@ rpcUdpXactDestroy(
 	RpcUdpXact xact
 	);
 
-/* send a transaction */
+/**
+ * Send a transaction.
+ */
 enum clnt_stat
 rpcUdpSend(
 	RpcUdpXact		xact,
@@ -144,7 +162,9 @@ rpcUdpSend(
 	...				/* 0 terminated xdrproc/pobj additional argument list */
 	);
 
-/* wait for a transaction to complete */
+/**
+ * @brief Wait for a transaction to complete.
+ */
 enum clnt_stat
 rpcUdpRcv(RpcUdpXact xact);
 
@@ -165,9 +185,11 @@ rpcUdpCallRp(
 );
 
 
-/* manage pools of transactions */
 
-/* A pool of transactions. The idea is not to malloc/free them
+/*
+ * @brief Manage pools of transactions.
+ *
+ * A pool of transactions. The idea is not to malloc/free them
  * all the time but keep a limited number around in a 'pool'.
  * Users who need a XACT may get it from the pool and put it back
  * when done.
@@ -205,4 +227,5 @@ rpcUdpXactPoolGet(RpcUdpXactPool pool, XactPoolGetMode mode);
 void
 rpcUdpXactPoolPut(RpcUdpXact xact);
 
+/** @} */
 #endif
diff --git a/cpukit/libfs/src/rfs/rtems-rfs-group.h b/cpukit/libfs/src/rfs/rtems-rfs-group.h
index 257eb49f34..90c6a9aa88 100644
--- a/cpukit/libfs/src/rfs/rtems-rfs-group.h
+++ b/cpukit/libfs/src/rfs/rtems-rfs-group.h
@@ -22,6 +22,13 @@
 #if !defined (_RTEMS_RFS_GROUP_H_)
 #define _RTEMS_RFS_GROUP_H_
 
+/**
+ * @defgroup rtems-rfs FS Group Management
+ *
+ * @ingroup rfs
+ * @{
+ */
+
 #include <rtems/rfs/rtems-rfs-trace.h>
 #include <rtems/rfs/rtems-rfs-bitmaps.h>
 #include <rtems/rfs/rtems-rfs-buffer.h>
@@ -34,6 +41,8 @@
 #define RTEMS_RFS_GROUP_INODE_BLOCK        (2)
 
 /**
+ * @brief Creates bit allocator for blocks in the group simpler.
+ *
  * A group is a selection of blocks on the disk. Typically the number of blocks
  * in a group is determined by the number of bits a block holds. This makes the
  * bit allocator for blocks in the group simpler plus is allows a simple way to
@@ -85,13 +94,15 @@ typedef struct _rtems_rfs_group
   (((_f)->group_inodes * (_g)) + (_i) + RTEMS_RFS_ROOT_INO)
 
 /**
- * Open a group. Allocate all the resources including the bitmaps.
+ * @brief Open a group.
+ *
+ * Allocate all the resources including the bitmaps.
  *
  * @param fs The file system.
  * @param base The base block number.
  * @param size The number of blocks in the group.
  * @param group Reference to the group to open.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
  */
 int rtems_rfs_group_open (rtems_rfs_file_system* fs,
                           rtems_rfs_buffer_block base,
@@ -100,24 +111,28 @@ int rtems_rfs_group_open (rtems_rfs_file_system* fs,
                           rtems_rfs_group*       group);
 
 /**
- * Close a group. Release all resources the group holds.
+ * @brief Close a group.
+ *
+ * Release all resources the group holds.
  *
  * @param fs The file system.
  * @param group The group to close.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
  */
 int rtems_rfs_group_close (rtems_rfs_file_system* fs,
                            rtems_rfs_group*       group);
 
 /**
- * Allocate an inode or block. The groups are searched to find the next
+ * @brief Allocate an inode or block.
+ *
+ * The groups are searched to find the next
  * available inode or block.
  *
  * @param fs The file system data.
  * @param goal The goal to seed the bitmap search.
  * @param inode If true allocate an inode else allocate a block.
  * @param result The allocated bit in the bitmap.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
  */
 int rtems_rfs_group_bitmap_alloc (rtems_rfs_file_system* fs,
                                   rtems_rfs_bitmap_bit   goal,
@@ -125,25 +140,25 @@ int rtems_rfs_group_bitmap_alloc (rtems_rfs_file_system* fs,
                                   rtems_rfs_bitmap_bit*  result);
 
 /**
- * Free the group allocated bit.
+ * @brief Free the group allocated bit.
  *
  * @param fs The file system data.
  * @param inode If true the number to free is an inode else it is a block.
  * @param block The inode or block number to free.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
  */
 int rtems_rfs_group_bitmap_free (rtems_rfs_file_system* fs,
                                  bool                   inode,
                                  rtems_rfs_bitmap_bit   no);
 
 /**
- * Test the group allocated bit.
+ * @brief Test the group allocated bit.
  *
  * @param fs The file system data.
  * @param inode If true the number to free is an inode else it is a block.
  * @param block The inode or block number to free.
  * @param state Return the state of the bit.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
  */
 int rtems_rfs_group_bitmap_test (rtems_rfs_file_system* fs,
                                  bool                   inode,
@@ -151,15 +166,16 @@ int rtems_rfs_group_bitmap_test (rtems_rfs_file_system* fs,
                                  bool*                  state);
 
 /**
- * Determine the number of blocks and inodes used.
+ * @brief Determine the number of blocks and inodes used.
  *
  * @param fs The file system data.
  * @param blocks The number of blocks used.
  * @param inodes The number of inodes used.
- * @return int The error number (errno). No error if 0.
+ * @retval int The error number (errno). No error if 0.
  */
 int rtems_rfs_group_usage (rtems_rfs_file_system* fs,
                            size_t*                blocks,
                            size_t*                inodes);
 
-#endif
+/** @} */
+#endif
\ No newline at end of file