libcsupport: Doxygen enhancement task #9

17 files changed, 160 insertions, 74 deletions

diff --git a/cpukit/libcsupport/include/rtems/gxx_wrappers.h b/cpukit/libcsupport/include/rtems/gxx_wrappers.h
index 2ef180a629..33b163043f 100644
--- a/cpukit/libcsupport/include/rtems/gxx_wrappers.h
+++ b/cpukit/libcsupport/include/rtems/gxx_wrappers.h
@@ -25,6 +25,14 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ *  @defgroup GxxWrappersSupport Gxx Wrappers Support
+ *
+ *  @ingroup libcsupport
+ *
+ *  @brief RTEMS Threads Compatibility Routines for Libgcc2
+ */
+
 /*
  * These typedefs should match with the ones defined in the file
  * gcc/gthr-rtems.h in the gcc distribution.
diff --git a/cpukit/libcsupport/include/rtems/libio.h b/cpukit/libcsupport/include/rtems/libio.h
index 5b7895d591..85bcb9774d 100644
--- a/cpukit/libcsupport/include/rtems/libio.h
+++ b/cpukit/libcsupport/include/rtems/libio.h
@@ -1176,9 +1176,9 @@ typedef struct {
 } rtems_filesystem_limits_and_options_t;
 
 /**
- * @brief Default pathconf settings.
+ *  @brief Default Pathconf Settings
  *
- * Override in a filesystem.
+ *  Override in a filesystem.
  */
 extern const rtems_filesystem_limits_and_options_t
   rtems_filesystem_default_pathconf;
@@ -1551,37 +1551,38 @@ int unmount(
 );
 
 /**
- * @brief Mounts a file system at @a target.
- *
- * The @a source may be a path to the corresponding device file, or @c NULL.
- * The @a target path must lead to an existing directory, or @c NULL.  In case
- * @a target is @c NULL, the root file system will be mounted.  The @a data
- * parameter will be forwarded to the file system initialization handler.  The
- * file system type is selected by @a filesystemtype and may be one of
- * - RTEMS_FILESYSTEM_TYPE_DEVFS,
- * - RTEMS_FILESYSTEM_TYPE_DOSFS,
- * - RTEMS_FILESYSTEM_TYPE_FTPFS,
- * - RTEMS_FILESYSTEM_TYPE_IMFS,
- * - RTEMS_FILESYSTEM_TYPE_MINIIMFS,
- * - RTEMS_FILESYSTEM_TYPE_NFS,
- * - RTEMS_FILESYSTEM_TYPE_RFS, or
- * - RTEMS_FILESYSTEM_TYPE_TFTPFS.
- *
- * Only configured or registered file system types are available.  You can add
- * file system types to your application configuration with
- * - CONFIGURE_FILESYSTEM_DEVFS,
- * - CONFIGURE_FILESYSTEM_DOSFS,
- * - CONFIGURE_FILESYSTEM_FTPFS,
- * - CONFIGURE_FILESYSTEM_IMFS,
- * - CONFIGURE_FILESYSTEM_MINIIMFS,
- * - CONFIGURE_FILESYSTEM_NFS,
- * - CONFIGURE_FILESYSTEM_RFS, and
- * - CONFIGURE_FILESYSTEM_TFTPFS.
- *
- * @see rtems_filesystem_register() and mount_and_make_target_path().
- *
- * @retval 0 Successful operation.
- * @retval -1 An error occured.  The @c errno indicates the error.
+ *  @brief Mounts a File System
+ *
+ *  The @a source may be a path to the corresponding device file, or @c NULL.
+ *  The @a target path must lead to an existing directory, or @c NULL.  
+ *  In case @a target is @c NULL, the root file system will be mounted.  
+ *  The @a data parameter will be forwarded to the file system
+ *  initialization handler.  The file system type is selected by
+ *  @a filesystemtype and may be one of
+ *  - RTEMS_FILESYSTEM_TYPE_DEVFS,
+ *  - RTEMS_FILESYSTEM_TYPE_DOSFS,
+ *  - RTEMS_FILESYSTEM_TYPE_FTPFS,
+ *  - RTEMS_FILESYSTEM_TYPE_IMFS,
+ *  - RTEMS_FILESYSTEM_TYPE_MINIIMFS,
+ *  - RTEMS_FILESYSTEM_TYPE_NFS,
+ *  - RTEMS_FILESYSTEM_TYPE_RFS, or
+ *  - RTEMS_FILESYSTEM_TYPE_TFTPFS.
+ *
+ *  Only configured or registered file system types are available.  
+ *  You can add file system types to your application configuration with
+ *  - CONFIGURE_FILESYSTEM_DEVFS,
+ *  - CONFIGURE_FILESYSTEM_DOSFS,
+ *  - CONFIGURE_FILESYSTEM_FTPFS,
+ *  - CONFIGURE_FILESYSTEM_IMFS,
+ *  - CONFIGURE_FILESYSTEM_MINIIMFS,
+ *  - CONFIGURE_FILESYSTEM_NFS,
+ *  - CONFIGURE_FILESYSTEM_RFS, and
+ *  - CONFIGURE_FILESYSTEM_TFTPFS.
+ *
+ *  @see rtems_filesystem_register() and mount_and_make_target_path().
+ *
+ *  @retval 0 Successful operation.
+ *  @retval -1 An error occured.  The @c errno indicates the error.
  */
 int mount(
   const char                 *source,
diff --git a/cpukit/libcsupport/include/rtems/libio_.h b/cpukit/libcsupport/include/rtems/libio_.h
index f56926acd9..7c5a29f0c3 100644
--- a/cpukit/libcsupport/include/rtems/libio_.h
+++ b/cpukit/libcsupport/include/rtems/libio_.h
@@ -179,14 +179,14 @@ extern rtems_filesystem_global_location_t rtems_filesystem_global_location_null;
    rtems_libio_check_permissions_with_error(_iop, _flag, EINVAL )
 
 /**
- * @brief Clones a node.
+ *  @brief Clones a Node
  *
- * The caller must hold the file system instance lock.
+ *  The caller must hold the file system instance lock.
  *
- * @param[out] clone The cloned location.
- * @param[in] master The master location.
+ *  @param[out] clone The cloned location.
+ *  @param[in] master The master location.
  *
- * @see rtems_filesystem_instance_lock().
+ *  @see rtems_filesystem_instance_lock().
  */
 void rtems_filesystem_location_clone(
   rtems_filesystem_location_info_t *clone,
diff --git a/cpukit/libcsupport/include/rtems/malloc.h b/cpukit/libcsupport/include/rtems/malloc.h
index 877bdbc0e4..a257674a38 100644
--- a/cpukit/libcsupport/include/rtems/malloc.h
+++ b/cpukit/libcsupport/include/rtems/malloc.h
@@ -157,7 +157,7 @@ void malloc_report_statistics_with_plugin(
 );
 
 /**
- *  @brief RTEMS variation on Aligned Memory Allocation
+ *  @brief RTEMS Variation on Aligned Memory Allocation
  *
  *  This method is a help memalign implementation which does all
  *  error checking done by posix_memalign() EXCEPT it does NOT
diff --git a/cpukit/libcsupport/src/clonenode.c b/cpukit/libcsupport/src/clonenode.c
index 0ac7c9ef40..3004def15b 100644
--- a/cpukit/libcsupport/src/clonenode.c
+++ b/cpukit/libcsupport/src/clonenode.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Clones a Node
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/fpathconf.c b/cpukit/libcsupport/src/fpathconf.c
index a48c5d35fc..104a3512e8 100644
--- a/cpukit/libcsupport/src/fpathconf.c
+++ b/cpukit/libcsupport/src/fpathconf.c
@@ -1,6 +1,11 @@
-/*
- *  fpathconf() - POSIX 1003.1b - 5.7.1 - Configurable Pathname Varables
+/**
+ *  @file
  *
+ *  @brief Configurable Pathname Varables
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,6 +24,9 @@
 #include <unistd.h>
 #include <errno.h>
 
+/**
+ *  POSIX 1003.1b - 5.7.1 - Configurable Pathname Varables
+ */
 long fpathconf(
   int   fd,
   int   name
diff --git a/cpukit/libcsupport/src/fsync.c b/cpukit/libcsupport/src/fsync.c
index 2bdf982090..885d32718a 100644
--- a/cpukit/libcsupport/src/fsync.c
+++ b/cpukit/libcsupport/src/fsync.c
@@ -1,6 +1,11 @@
-/*
- *  fsync() - POSIX 1003.1b 6.6.1 - Synchronize the State of a File
+/**
+ *  @file
  *
+ *  @brief Synchronize the State of a File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,6 +23,9 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
+/**
+ *  POSIX 1003.1b 6.6.1 - Synchronize the State of a File
+ */
 int fsync(
   int     fd
 )
diff --git a/cpukit/libcsupport/src/gxx_wrappers.c b/cpukit/libcsupport/src/gxx_wrappers.c
index 2979da4b38..cd1ecc6339 100644
--- a/cpukit/libcsupport/src/gxx_wrappers.c
+++ b/cpukit/libcsupport/src/gxx_wrappers.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS threads compatibility routines for libgcc2.
+/**
+ *  @file
  *
+ *  @brief RTEMS Threads Compatibility Routines for Libgcc2
+ *  @ingroup GxxWrappersSupport
+ */
+
+/*
  *  by: Rosimildo da Silva (rdasilva@connecttel.com)
  *
  *  Used ideas from:
diff --git a/cpukit/libcsupport/src/issetugid.c b/cpukit/libcsupport/src/issetugid.c
index 375fea8d9b..0cb870ea00 100644
--- a/cpukit/libcsupport/src/issetugid.c
+++ b/cpukit/libcsupport/src/issetugid.c
@@ -1,12 +1,20 @@
-/*
- *  Dummy version of BSD routine
+/**
+ *  @file
+ *
+ *  @brief Dummy Version of BSD Routine
+ *  @ingroup libcsupport
  */
 
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE_ISSETUGID)
+
+/**
+ *  Dummy version of BSD routine
+ */
 int issetugid (void)
 {
   return 0;
diff --git a/cpukit/libcsupport/src/lstat.c b/cpukit/libcsupport/src/lstat.c
index 3cf93bee27..abdc0465cd 100644
--- a/cpukit/libcsupport/src/lstat.c
+++ b/cpukit/libcsupport/src/lstat.c
@@ -1,6 +1,11 @@
-/*
- *  lstat() - BSD 4.3 and SVR4 - Get File Status
+/**
+ *  @file
  *
+ *  @brief Get File Status
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,3 +23,7 @@
 #define _STAT_FOLLOW_LINKS RTEMS_FS_FOLLOW_HARD_LINK
 
 #include "stat.c"
+
+/**
+ *  BSD 4.3 and SVR4 - Get File Status
+ */
\ No newline at end of file
diff --git a/cpukit/libcsupport/src/mount.c b/cpukit/libcsupport/src/mount.c
index 8eb4796fb2..92033e1904 100644
--- a/cpukit/libcsupport/src/mount.c
+++ b/cpukit/libcsupport/src/mount.c
@@ -1,12 +1,11 @@
-/*
- *  mount()
- *
- *  XXX
- *
- *  XXX make sure no required ops are NULL
- *  XXX make sure no optional ops you are using are NULL
- *  XXX unmount should be required.
+/**
+ *  @file
  *
+ *  @brief Mounts a File System
+ *  @ingroup FileSystemTypesAndMount
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,9 +27,6 @@
 
 RTEMS_CHAIN_DEFINE_EMPTY(rtems_filesystem_mount_table);
 
-/*
- * Default pathconfs.
- */
 const rtems_filesystem_limits_and_options_t rtems_filesystem_default_pathconf = {
    5,    /* link_max: count */
    128,  /* max_canon: max formatted input line size */
diff --git a/cpukit/libcsupport/src/pathconf.c b/cpukit/libcsupport/src/pathconf.c
index c337d44955..690817c3e8 100644
--- a/cpukit/libcsupport/src/pathconf.c
+++ b/cpukit/libcsupport/src/pathconf.c
@@ -1,6 +1,11 @@
-/*
- *  pathconf() - POSIX 1003.1b - 5.7.1 - Configurable Pathname Varables
+/**
+ *  @file
  *
+ *  @brief Configurable Pathname Varables
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,6 +24,9 @@
 #include <sys/stat.h>
 #include <fcntl.h>
 
+/**
+ *  POSIX 1003.1b - 5.7.1 - Configurable Pathname Varables
+ */
 long pathconf(
   const char *path,
   int         name
diff --git a/cpukit/libcsupport/src/printk.c b/cpukit/libcsupport/src/printk.c
index 0a2989226c..badbd0d591 100644
--- a/cpukit/libcsupport/src/printk.c
+++ b/cpukit/libcsupport/src/printk.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Kernel Printf Function
+ *  @ingroup libcsupport
+ */
+
 /*
  * (C) Copyright 1997 -
  * - NavIST Group - Real-Time Distributed Systems and Industrial Automation
@@ -22,10 +29,8 @@
 #include <stdio.h>
 #include <rtems/bspIo.h>
 
-/*
- * printk
- *
- * Kernel printf function requiring minimal infrastructure.
+/**
+ *  Kernel printf function requiring minimal infrastructure.
  */
 void printk(const char *fmt, ...)
 {
diff --git a/cpukit/libcsupport/src/privateenv.c b/cpukit/libcsupport/src/privateenv.c
index 04622fd432..f5fd67db95 100644
--- a/cpukit/libcsupport/src/privateenv.c
+++ b/cpukit/libcsupport/src/privateenv.c
@@ -1,12 +1,11 @@
 /**
- * @file
+ *  @file
  *
- * @ingroup LibIOEnv
+ *  @brief Instantiate a Private User Environment
+ *  @ingroup LibIOEnv
  */
 
 /*
- *  Instantiate a private user environment for the calling thread.
- *
  *  Submitted by: fernando.ruiz@ctv.es (correo@fernando-ruiz.com)
  *
  *  COPYRIGHT (c) 1989-2010.
@@ -28,6 +27,10 @@
 #include <rtems/libio_.h>
 #include <rtems/score/thread.h>
 
+/**
+ *  Instantiate a private user environment for the calling thread.
+ */
+
 static void free_user_env(void *arg)
 {
   rtems_user_env_t *env = arg;
diff --git a/cpukit/libcsupport/src/rmdir.c b/cpukit/libcsupport/src/rmdir.c
index 5e4c9f15be..4802aa364c 100644
--- a/cpukit/libcsupport/src/rmdir.c
+++ b/cpukit/libcsupport/src/rmdir.c
@@ -1,6 +1,11 @@
-/*
- *  rmdir() - POSIX 1003.1b - 5.2.2 - Remove a Directory
+/**
+ *  @file
  *
+ *  @brief Remove a Directory
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,6 +22,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *   POSIX 1003.1b - 5.2.2 - Remove a Directory
+ */
 int rmdir( const char *path )
 {
   int rv = 0;
diff --git a/cpukit/libcsupport/src/rtems_memalign.c b/cpukit/libcsupport/src/rtems_memalign.c
index b7760372f4..64bb489dae 100644
--- a/cpukit/libcsupport/src/rtems_memalign.c
+++ b/cpukit/libcsupport/src/rtems_memalign.c
@@ -1,6 +1,11 @@
-/*
- *  rtems_memalign() - Raw aligned allocate from Protected Heap
+/**
+ *  @file
  *
+ *  @brief RTEMS Variation on Aligned Memory Allocation
+ *  @ingroup MallocSupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/seteuid.c b/cpukit/libcsupport/src/seteuid.c
index 406cc9ff24..6495decdc3 100644
--- a/cpukit/libcsupport/src/seteuid.c
+++ b/cpukit/libcsupport/src/seteuid.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Set Effective User Id
+ *  @ingroup libcsupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).