libfs: Doxygen Enhancement Task #2

http://www.google-melange.com/gci/task/view/google/gci2012/8032207

cpukit/libfs/src/imfs/deviceio.c

@@ -1,9 +1,11 @@
+/**
+ * @file
+ *
+ * @brief IMFS Device Node Handlers
+ * @ingroup IMFS
+ */
+
 /*
- *  IMFS Device Node Handlers
- *
- *  This file contains the set of handlers used to map operations on
- *  IMFS device nodes onto calls to the RTEMS Classic API IO Manager.
- *
  *  COPYRIGHT (c) 1989-2012.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libfs/src/imfs/imfs.h

@@ -1,7 +1,7 @@
 /**
  * @file rtems/imfs.h
  *
- * Header file for the In-Memory File System
+ * @brief Header file for the In-Memory File System
  */
 
 /*
@@ -21,6 +21,12 @@
 #include <rtems/libio_.h>
 #include <rtems/pipe.h>
 
+/**
+ * @defgroup IMFS POSIX In-Memory File System Support
+ *
+ * @brief In-Memory File System Support
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -158,6 +164,9 @@ typedef IMFS_jnode_t *(*IMFS_node_control_initialize)(
   const IMFS_types_union *info
 );
 
+/**
+ * @brief Initialize Default IMFS Node 
+ */
 IMFS_jnode_t *IMFS_node_initialize_default(
   IMFS_jnode_t *node,
   const IMFS_types_union *info
@@ -172,12 +181,18 @@ typedef IMFS_jnode_t *(*IMFS_node_control_remove)(
   IMFS_jnode_t *node
 );
 
+/**
+ * @brief Remove Default IMFS Node 
+ */
 IMFS_jnode_t *IMFS_node_remove_default(
   IMFS_jnode_t *node
 );
 
 typedef IMFS_jnode_t *(*IMFS_node_control_destroy)( IMFS_jnode_t *node );
 
+/**
+ * @brief Destroy Default IMFS Node 
+ */
 IMFS_jnode_t *IMFS_node_destroy_default( IMFS_jnode_t *node );
 
 typedef struct {
@@ -298,6 +313,9 @@ extern int miniIMFS_initialize(
    const void                           *data
 );
 
+/**
+ * @brief IMFS Initialization Support
+ */
 extern int IMFS_initialize_support(
   rtems_filesystem_mount_table_entry_t *mt_entry,
   const rtems_filesystem_operations_table *op_table,
@@ -322,21 +340,44 @@ extern void IMFS_dump( void );
  */
 extern int IMFS_memfile_maximum_size( void );
 
+/**
+ * @brief Destroy IMFS Node
+ */
 extern void IMFS_node_destroy( IMFS_jnode_t *node );
 
+/**
+ * @brief Clone IMFS Node
+ */
 extern int IMFS_node_clone( rtems_filesystem_location_info_t *loc );
 
+/**
+ * @brief Free IMFS Node
+ */
 extern void IMFS_node_free( const rtems_filesystem_location_info_t *loc );
 
+/**
+ * @brief IMFS Node Type
+ * 
+ * The following verifies that returns the type of node that the
+ * loc refers to.
+ */
 extern rtems_filesystem_node_types_t IMFS_node_type(
   const rtems_filesystem_location_info_t *loc
 );
 
+/**
+ * @brief IMFS Stat
+ * 
+ * This routine provides a stat for the IMFS file system.
+ */
 extern int IMFS_stat(
   const rtems_filesystem_location_info_t *loc,
   struct stat *buf
 );
 
+/**
+ * @brief Evaluation IMFS Node Support
+ */
 extern void IMFS_eval_path(
   rtems_filesystem_eval_path_context_t *ctx
 );
@@ -362,6 +403,11 @@ extern int IMFS_mknod(
   dev_t dev
 );
 
+/**
+ * @brief Create a New IMFS Node
+ * 
+ * Routine to create a new in memory file system node.
+ */
 extern IMFS_jnode_t *IMFS_allocate_node(
   IMFS_fs_info_t *fs_info,
   const IMFS_node_control *node_control,
@@ -371,6 +417,12 @@ extern IMFS_jnode_t *IMFS_allocate_node(
   const IMFS_types_union *info
 );
 
+/**
+ * @brief Create an IMFS Node
+ * 
+ * Create an IMFS filesystem node of an arbitrary type that is NOT
+ * the root directory node.
+ */
 extern IMFS_jnode_t *IMFS_create_node_with_control(
   const rtems_filesystem_location_info_t *parentloc,
   const IMFS_node_control *node_control,
@@ -391,6 +443,9 @@ extern int IMFS_make_generic_node(
   void *context
 );
 
+/**
+ * @brief Mount an IMFS
+ */
 extern int IMFS_mount(
   rtems_filesystem_mount_table_entry_t *mt_entry  /* IN */
 );
@@ -433,6 +488,16 @@ extern ssize_t memfile_write(
   size_t         count            /* IN  */
 );
 
+/**
+ * @name IMFS Device Node Handlers
+ *
+ * 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  */
   const char    *pathname,       /* IN  */
@@ -467,12 +532,24 @@ extern int device_ftruncate(
   off_t          length             /* IN  */
 );
 
+/** @} */
+
+/**
+ * @brief Set IMFS File Access and Modification Times
+ * 
+ * 
+ * This routine is the implementation of the utime() system
+ * call for the IMFS.
+ */
 extern int IMFS_utime(
   const rtems_filesystem_location_info_t *loc,
   time_t actime,
   time_t modtime
 );
 
+/**
+ * @brief Change IMFS File Mode
+ */
 extern int IMFS_fchmod(
   const rtems_filesystem_location_info_t *loc,
   mode_t mode

cpukit/libfs/src/imfs/imfs_creat.c

@@ -1,8 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Create an IMFS Node
+ * @ingroup IMFS
+ */
 /*
- *  IMFS_create_node()
- *
- *  Routine to create a new in memory file system node.
- *
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -83,10 +85,6 @@ IMFS_jnode_t *IMFS_allocate_node(
   return (*node->control->node_initialize)( node, info );
 }
 
-/*
- *  Create an IMFS filesystem node of an arbitrary type that is NOT
- *  the root directory node.
- */
 IMFS_jnode_t *IMFS_create_node_with_control(
   const rtems_filesystem_location_info_t *parentloc,
   const IMFS_node_control *node_control,

cpukit/libfs/src/imfs/imfs_eval.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  Evaluation IMFS Node Support Routines
+ * @file
  *
+ * @brief Evaluation IMFS Node Support
+ * @ingroup IMFS
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libfs/src/imfs/imfs_fchmod.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  IMFS file change mode routine.
+ * @file
  *
+ * @brief Change IMFS File Mode
+ * @ingroup IMFS
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libfs/src/imfs/imfs_initsupp.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  IMFS Initialization
+ * @file
  *
+ * @brief IMFS Node Support
+ * @ingroup IMFS
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libfs/src/imfs/imfs_mount.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  IMFS_mount
+ * @file
  *
+ * @brief Mount an IMFS
+ * @ingroup IMFS
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libfs/src/imfs/imfs_ntype.c

@@ -1,9 +1,11 @@
+/**
+ * @file
+ *
+ * @brief IMFS Node Type
+ * @ingroup IMFS
+ */
+
 /*
- *  IMFS_node_type
- *
- *  The following verifies that returns the type of node that the
- *  loc refers to.
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libfs/src/imfs/imfs_stat.c

@@ -1,8 +1,11 @@
+/**
+ * @file
+ *
+ * @brief IMFS Stat
+ * @ingroup IMFS
+ */
+
 /*
- *  IMFS_stat
- *
- *  This routine provides a stat for the IMFS file system.
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libfs/src/imfs/imfs_utime.c

@@ -1,9 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Set IMFS File Access and Modification Times
+ * @ingroup IMFS
+ */
+
 /*
- *  IMFS_utime
- *
- *  This routine is the implementation of the utime() system
- *  call for the IMFS.
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libfs/src/imfs/ioman.c

@@ -1,7 +1,11 @@
-/*
+/**
- *  This file emulates the old Classic RTEMS IO manager directives
+ * @file
- *  which register and lookup names using the in-memory filesystem.
  *
+ * @brief RTMES Register IO Name
+ * @ingroup ClassicIO
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -22,12 +26,6 @@
 
 #include <rtems/libio_.h>
 
-/*
- *  rtems_io_register_name
- *
- *  This assumes that all registered devices are character devices.
- */
-
 rtems_status_code rtems_io_register_name(
   const char                *device_name,
   rtems_device_major_number  major,

cpukit/libfs/src/pipe/fifo.c

@@ -1,6 +1,11 @@
-/*
+/**
- * fifo.c: POSIX FIFO/pipe for RTEMS
+ * @file
  *
+ * @brief FIFO/Pipe Support
+ * @ingroup FIFO_PIPE
+ */
+
+/*
  * Author: Wei Shen <cquark@gmail.com>
  *
  * The license and distribution terms for this file may be
@@ -236,12 +241,6 @@ out:
   return err;
 }
 
-/*
- * Interface to file system close.
- *
- * *pipep points to pipe control structure. When the last user releases pipe,
- * it will be set to NULL.
- */
 void pipe_release(
   pipe_control_t **pipep,
   rtems_libio_t *iop
@@ -299,13 +298,6 @@ void pipe_release(
 
 }
 
-/*
- * Interface to file system open.
- *
- * *pipep points to pipe control structure. If called with *pipep = NULL,
- * fifo_open will try allocating and initializing a control structure. If the
- * call succeeds, *pipep will be set to address of new control structure.
- */
 int fifo_open(
   pipe_control_t **pipep,
   rtems_libio_t *iop
@@ -387,9 +379,6 @@ out_error:
   return err;
 }
 
-/*
- * Interface to file system read.
- */
 ssize_t pipe_read(
   pipe_control_t *pipe,
   void           *buffer,
@@ -459,9 +448,6 @@ out_nolock:
   return ret;
 }
 
-/*
- * Interface to file system write.
- */
 ssize_t pipe_write(
   pipe_control_t *pipe,
   const void     *buffer,
@@ -545,9 +531,6 @@ out_nolock:
   return ret;
 }
 
-/*
- * Interface to file system ioctl.
- */
 int pipe_ioctl(
   pipe_control_t  *pipe,
   ioctl_command_t  cmd,

cpukit/libfs/src/pipe/pipe.c

@@ -1,6 +1,11 @@
-/*
+/**
- * pipe.c: anonymous pipe
+ * @file
  *
+ * @brief Create an Anonymous Pipe
+ * @ingroup FIFO_PIPE
+ */
+
+/*
  * Author: Wei Shen <cquark@gmail.com>
  *
  * The license and distribution terms for this file may be
@@ -22,9 +27,6 @@
 /* FIXME: This approach is questionable */
 static uint16_t rtems_pipe_no = 0;
 
-/*
- * Called by pipe() to create an anonymous pipe.
- */
 int pipe_create(
   int filsdes[2]
 )

cpukit/libfs/src/pipe/pipe.h

@@ -22,6 +22,12 @@
 extern "C" {
 #endif
 
+/**
+ * @defgroup FIFO_PIPE FIFO/pipe File System Support
+ * 
+ * @brief Interface to the POSIX FIFO/pipe File System
+ */
+
 /* Control block to manage each pipe */
 typedef struct pipe_control {
   char *Buffer;
@@ -42,14 +48,18 @@ typedef struct pipe_control {
 #endif
 } pipe_control_t;
 
-/*
+/**
+ * @brief Create an Anonymous Pipe
+ * 
  * Called by pipe() to create an anonymous pipe.
  */
 extern int pipe_create(
   int filsdes[2]
 );
 
-/*
+/**
+ * @brief Release a Pipe
+ * 
  * Interface to file system close.
  *
  * *pipep points to pipe control structure. When the last user releases pipe,
@@ -60,7 +70,8 @@ extern void pipe_release(
   rtems_libio_t *iop
 );
 
-/*
+/**
+ * @brief FIFO Open
  * Interface to file system open.
  *
  * *pipep points to pipe control structure. If called with *pipep = NULL,
@@ -72,7 +83,9 @@ extern int fifo_open(
   rtems_libio_t *iop
 );
 
-/*
+/**
+ * @brief Pipe Read
+ * 
  * Interface to file system read.
  */
 extern ssize_t pipe_read(
@@ -82,7 +95,9 @@ extern ssize_t pipe_read(
   rtems_libio_t  *iop
 );
 
-/*
+/**
+ * @brief Pipe Write
+ * 
  * Interface to file system write.
  */
 extern ssize_t pipe_write(
@@ -92,7 +107,9 @@ extern ssize_t pipe_write(
   rtems_libio_t  *iop
 );
 
-/*
+/**
+ * @brief Pipe IO Control
+ * 
  * Interface to file system ioctl.
  */
 extern int pipe_ioctl(

cpukit/libfs/src/rfs/rtems-rfs-bitmaps.c

@@ -1,3 +1,15 @@
+/**
+ * @file
+ *
+ * @brief RTEMS File Systems Bitmap Routines
+ * @ingroup rtems-rfs
+ * 
+ * These functions manage bit maps. A bit map consists of the map of bit
+ * allocated in a block and a search map where a bit represents 32 actual
+ * bits. The search map allows for a faster search for an available bit as 32
+ * search bits can checked in a test.
+ */
+
 /*
  *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
  *
@@ -5,18 +17,6 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
-/**
- * @file
- *
- * @ingroup rtems-rfs
- *
- * RTEMS File Systems Bitmap Routines.
- *
- * These functions manage bit maps. A bit map consists of the map of bit
- * allocated in a block and a search map where a bit represents 32 actual
- * bits. The search map allows for a faster search for an available bit as 32
- * search bits can checked in a test.
- */
 
 #if HAVE_CONFIG_H
 #include "config.h"

cpukit/libfs/src/rfs/rtems-rfs-block.c

@@ -1,21 +1,13 @@
-/*
- *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
- *
- *  The license and distribution terms for this file may be
- *  found in the file LICENSE in this distribution or at
- *  http://www.rtems.com/license/LICENSE.
- */
 /**
  * @file
  *
+ * @brief RTEMS File Systems Block Routines
  * @ingroup rtems-rfs
- *
+ * 
- * RTEMS File Systems Block Routines.
- *
  * These functions manage blocks in the RFS file system. A block is an area of
  * the media and its size is set for a each specific media. The block size is
- * set when the file system is set up and needs to be matched for it to be read
+ * set when the file system is set up and needs to be matched for it to be 
- * correctly.
+ * read correctly.
  *
  * Blocks are managed as groups. A block group or "group" is part of the total
  * number of blocks being managed by the file system and exist to allow
@@ -26,12 +18,20 @@
  * A group consist of a block bitmap, inodes and data blocks. The first block
  * of the file system will hold the superblock. The block bitmap is a
  * collection of blocks that hold a map of bits, one bit per block for each
- * block in the group. When a file system is mounted the block bitmaps are read
+ * block in the group. When a file system is mounted the block bitmaps are 
- * and a summary bit map is made. The summary bitmap has a single bit for 32
+ * read and a summary bit map is made. The summary bitmap has a single bit for
- * bits in the bitmap and is set when all 32 bits it maps to are set. This
+ * 32 bits in the bitmap and is set when all 32 bits it maps to are set. This
  * speeds up the search for a free block by a factor of 32.
  */
 
+/*
+ *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
+ *
+ *  The license and distribution terms for this file may be
+ *  found in the file LICENSE in this distribution or at
+ *  http://www.rtems.com/license/LICENSE.
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif

cpukit/libfs/src/rfs/rtems-rfs-dir-hash.c

@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief RTEMS File Systems Directory Hash function
  * @ingroup rtems-rfs
- *
- * RTEMS File Systems Directory Hash function.
  */
 
 #if HAVE_CONFIG_H

cpukit/libfs/src/rfs/rtems-rfs-inode.c

@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @brief RTEMS File Systems Inode Routines
+ * @ingroup rtems-rfs
+ * 
+ * These functions manage inodes in the RFS file system. An inode is part of a
+ * block that reside after the bitmaps in the group.
+ */
 /*
  *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
  *
@@ -5,16 +14,6 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
-/**
- * @file
- *
- * @ingroup rtems-rfs
- *
- * RTEMS File Systems Inode Routines.
- *
- * These functions manage inodes in the RFS file system. An inode is part of a
- * block that reside after the bitmaps in the group.
- */
 
 #if HAVE_CONFIG_H
 #include "config.h"

cpukit/libfs/src/rfs/rtems-rfs-link.c

@@ -1,3 +1,13 @@
+/**
+ * @file
+ *
+ * @brief RTEMS File Systems Link Routines
+ * @ingroup rtems-rfs
+ * 
+ * These functions manage links. A link is the addition of a directory entry
+ * in a parent directory and incrementing the links count in the inode.
+ */
+
 /*
  *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
  *
@@ -5,16 +15,6 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
-/**
- * @file
- *
- * @ingroup rtems-rfs
- *
- * RTEMS File Systems Link Routines.
- *
- * These functions manage links. A link is the addition of a directory entry in
- * a parent directory and incrementing the links count in the inode.
- */
 
 #if HAVE_CONFIG_H
 #include "config.h"

cpukit/libfs/src/rfs/rtems-rfs-mutex.c

@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief RTEMS File System Mutex
+ * @ingroup rtems-rfs
+ */
 /*
  *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
  *
@@ -5,13 +11,6 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
-/**
- * @file
- *
- * @ingroup rtems-rfs
- *
- * RTEMS File System Mutex.
- */
 
 #if HAVE_CONFIG_H
 #include "config.h"

cpukit/libfs/src/rfs/rtems-rfs-rtems-dev.c

@@ -1,3 +1,13 @@
+/**
+ * @file
+ *
+ * @brief RTEMS RFS Device Interface
+ * @ingroup rtems-rfs
+ * 
+ * This file contains the set of handlers used to map operations on RFS device
+ * nodes onto calls to the RTEMS Classic API IO Manager.
+ */
+
 /*
  *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
  *
@@ -5,17 +15,6 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
-/**
- * @file
- *
- * @ingroup rtems-rfs
- *
- * RTEMS RFS Device Interface.
- *
- * This file contains the set of handlers used to map operations on RFS device
- * nodes onto calls to the RTEMS Classic API IO Manager.
- *
- */
 
 #if HAVE_CONFIG_H
   #include "config.h"

cpukit/libfs/src/rfs/rtems-rfs-rtems.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief RTEMS File System Interface for RTEMS
+ * @ingroup rtems-rfs
+ */
+
 /*
  *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
  *
@@ -8,13 +15,6 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  */
-/**
- * @file
- *
- * @ingroup rtems-rfs
- *
- * RTEMS File System Interface for RTEMS.
- */
 
 #if HAVE_CONFIG_H
 #include "config.h"

cpukit/sapi/include/rtems/io.h

@@ -4,6 +4,9 @@
  * @ingroup ClassicIO
  *
  * @brief Classic Input/Output Manager API.
+ * 
+ * This file emulates the old Classic RTEMS IO manager directives
+ * which register and lookup names using the in-memory filesystem.
  */
 
 /*
@@ -115,9 +118,11 @@ rtems_status_code rtems_io_unregister_driver(
 /**
  * @brief Registers the name @a device_name in the file system for the device
  * with number tuple @a major and @a minor.
+ * 
+ * This assumes that all registered devices are character devices.
  *
  * @retval RTEMS_SUCCESSFUL Name successfully registered.
- * @retval RTEMS_TOO_MANY Name already in use or other errors.
+ * @retval RTEMS_TOO_MANY Name already in use or other errors. 
  */
 rtems_status_code rtems_io_register_name(
   const char *device_name,