libcsupport: Doxygen enhancement task #2

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

24 files changed, 209 insertions, 58 deletions

diff --git a/cpukit/libcsupport/include/rtems/assoc.h b/cpukit/libcsupport/include/rtems/assoc.h
index 80a2fe7cdf..2401661e1f 100644
--- a/cpukit/libcsupport/include/rtems/assoc.h
+++ b/cpukit/libcsupport/include/rtems/assoc.h
@@ -32,6 +32,9 @@ typedef struct {
 
 #define RTEMS_ASSOC_DEFAULT_NAME "(default)"
 
+/**
+ *  @brief RTEMS Associate Pointer by Name
+ */
 const rtems_assoc_t *rtems_assoc_ptr_by_name(
   const rtems_assoc_t *,
   const char *
@@ -52,6 +55,9 @@ uint32_t rtems_assoc_local_by_remote(
   uint32_t
 );
 
+/**
+ *  @brief RTEMS Associate Remote by Name
+ */
 uint32_t rtems_assoc_remote_by_name(
   const rtems_assoc_t *,
   const char *
diff --git a/cpukit/libcsupport/include/rtems/libcsupport.h b/cpukit/libcsupport/include/rtems/libcsupport.h
index 919b41eea3..a3e5517046 100644
--- a/cpukit/libcsupport/include/rtems/libcsupport.h
+++ b/cpukit/libcsupport/include/rtems/libcsupport.h
@@ -27,7 +27,17 @@
 extern "C" {
 #endif
 
+/**
+ *  @defgroup libcsupport Standard C Library Support
+ *
+ *  @brief RTEMS Specific Support for the Standard C Library
+ */
+
 extern void malloc_dump(void);
+
+/**
+ *  @brief Malloc Walk
+ */
 extern bool malloc_walk(int source, bool printf_enabled);
 void malloc_set_heap_pointer(Heap_Control *new_heap);
 Heap_Control *malloc_get_heap_pointer( void );
diff --git a/cpukit/libcsupport/include/rtems/libio_.h b/cpukit/libcsupport/include/rtems/libio_.h
index 98f6f63d4d..91035b1757 100644
--- a/cpukit/libcsupport/include/rtems/libio_.h
+++ b/cpukit/libcsupport/include/rtems/libio_.h
@@ -399,6 +399,9 @@ typedef struct {
   rtems_filesystem_eval_path_eval_token eval_token;
 } rtems_filesystem_eval_path_generic_config;
 
+/**
+ *  @brief RTEMS File System Eval Generic Path
+ */
 void rtems_filesystem_eval_path_generic(
   rtems_filesystem_eval_path_context_t *ctx,
   void *arg,
@@ -535,7 +538,9 @@ static inline void rtems_filesystem_location_error(
     errno = eno;
   }
 }
-
+/**
+ *  @brief RTEMS File System Mknod
+ */
 int rtems_filesystem_mknod(
   const rtems_filesystem_location_info_t *parentloc,
   const char *name,
diff --git a/cpukit/libcsupport/include/rtems/termiostypes.h b/cpukit/libcsupport/include/rtems/termiostypes.h
index 74653b0252..7f2a3eae84 100644
--- a/cpukit/libcsupport/include/rtems/termiostypes.h
+++ b/cpukit/libcsupport/include/rtems/termiostypes.h
@@ -26,6 +26,14 @@
 extern "C" {
 #endif
 
+/**
+ *  @defgroup TermiostypesSupport RTEMS Termios Device Support
+ *
+ *  @ingroup libcsupport
+ *
+ *  @brief RTEMS Termios Device Support Internal Data Structures
+ */
+
 /*
  * Wakeup callback data structure
  */
@@ -186,11 +194,11 @@ typedef uint32_t rtems_termios_baud_t;
 extern const rtems_assoc_t rtems_termios_baud_table [];
 
 /**
- * @brief Converts the integral baud value @a baud to the Termios control flag
- * representation.
+ *  @brief Converts the Integral Baud value @a baud to the Termios Control Flag
+ *  Representation
  *
- * @retval B0 Invalid baud value or a baud value of 0.
- * @retval other Baud constant according to @a baud.
+ *  @retval B0 Invalid baud value or a baud value of 0.
+ *  @retval other Baud constant according to @a baud.
  */
 tcflag_t rtems_termios_number_to_baud(rtems_termios_baud_t baud);
 
@@ -205,7 +213,9 @@ tcflag_t rtems_termios_number_to_baud(rtems_termios_baud_t baud);
  */
 rtems_termios_baud_t rtems_termios_baud_to_number(tcflag_t c_cflag);
 
-/* convert Bxxx constant to index */
+/** 
+ *  @brief Convert Bxxx Constant to Index 
+ */
 int  rtems_termios_baud_to_index(rtems_termios_baud_t termios_baud);
 
 /**
diff --git a/cpukit/libcsupport/src/assocptrbyname.c b/cpukit/libcsupport/src/assocptrbyname.c
index 1afc12e382..a01b9cb143 100644
--- a/cpukit/libcsupport/src/assocptrbyname.c
+++ b/cpukit/libcsupport/src/assocptrbyname.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Pointer by Name
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H
diff --git a/cpukit/libcsupport/src/assocremotebyname.c b/cpukit/libcsupport/src/assocremotebyname.c
index 0233d468da..8a894fc896 100644
--- a/cpukit/libcsupport/src/assocremotebyname.c
+++ b/cpukit/libcsupport/src/assocremotebyname.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Remote by Name
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H
diff --git a/cpukit/libcsupport/src/dup2.c b/cpukit/libcsupport/src/dup2.c
index ba60acb85b..37c93a7398 100644
--- a/cpukit/libcsupport/src/dup2.c
+++ b/cpukit/libcsupport/src/dup2.c
@@ -1,6 +1,11 @@
-/*
- *  dup2() - POSIX 1003.1b 6.2.1 Duplicate an Open File Descriptor
+/**
+ *  @file
  *
+ *  @brief Duplicate an Open File Descriptor
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,6 +23,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 6.2.1 Duplicate an Open File Descriptor
+ */
 int dup2(
   int fildes,
   int fildes2
diff --git a/cpukit/libcsupport/src/fchown.c b/cpukit/libcsupport/src/fchown.c
index 6dfbc52ff3..ec84fe4f47 100644
--- a/cpukit/libcsupport/src/fchown.c
+++ b/cpukit/libcsupport/src/fchown.c
@@ -1,6 +1,11 @@
-/*
- *  fchown() - POSIX 1003.1b 5.6.5 - Change Owner and Group of a File
+/**
+ *  @file
  *
+ *  @brief Change Owner and Group of a File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,6 +22,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.6.5 - Change Owner and Group of a File
+ */
 int fchown( int fd, uid_t owner, gid_t group )
 {
   int rv = 0;
diff --git a/cpukit/libcsupport/src/getgroups.c b/cpukit/libcsupport/src/getgroups.c
index d6eebb852c..6bf58a70fe 100644
--- a/cpukit/libcsupport/src/getgroups.c
+++ b/cpukit/libcsupport/src/getgroups.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get Supplementary IDs
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -5,10 +12,9 @@
 #include <sys/types.h>
 #include <unistd.h>
 
-/*
+/**
  *  4.2.3 Get Supplementary IDs, P1003.1b-1993, p. 86
  */
-
 int getgroups(
   int    gidsetsize __attribute__((unused)),
   gid_t  grouplist[] __attribute__((unused))
diff --git a/cpukit/libcsupport/src/isatty_r.c b/cpukit/libcsupport/src/isatty_r.c
index 56751dc008..13ba6b4b34 100644
--- a/cpukit/libcsupport/src/isatty_r.c
+++ b/cpukit/libcsupport/src/isatty_r.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Test for a Terminal Device
+ *  @ingroup libcsupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
@@ -11,14 +18,11 @@
 #include "config.h"
 #endif
 
-/*
- *  _isatty_r
- *
- *  This is the Newlib dependent reentrant version of isatty().
- */
-
 #if defined(RTEMS_NEWLIB) && !defined(HAVE__ISATTY_R)
 
+ /**
+ *  This is the Newlib dependent reentrant version of isatty().
+ */
 #include <unistd.h>
 #include <reent.h>
 #include <sys/stat.h>
diff --git a/cpukit/libcsupport/src/link.c b/cpukit/libcsupport/src/link.c
index f49cca2302..7ec103c15c 100644
--- a/cpukit/libcsupport/src/link.c
+++ b/cpukit/libcsupport/src/link.c
@@ -1,6 +1,11 @@
-/*
- *  link() - POSIX 1003.1b - 5.3.4 - Create a new link
+/**
+ *  @file
  *
+ *  @brief Create a new link
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,6 +22,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  link() - POSIX 1003.1b - 5.3.4 - Create a new link
+ */
 int link( const char *path1, const char *path2 )
 {
   int rv = 0;
@@ -50,16 +58,13 @@ int link( const char *path1, const char *path2 )
   return rv;
 }
 
-/*
- *  _link_r
- *
- *  This is the Newlib dependent reentrant version of link().
- */
-
 #if defined(RTEMS_NEWLIB)
 
 #include <reent.h>
 
+/**
+ *  This is the Newlib dependent reentrant version of link().
+ */
 int _link_r(
   struct _reent *ptr __attribute__((unused)),
   const char    *path1,
diff --git a/cpukit/libcsupport/src/malloc_walk.c b/cpukit/libcsupport/src/malloc_walk.c
index fa810888c9..d06106beef 100644
--- a/cpukit/libcsupport/src/malloc_walk.c
+++ b/cpukit/libcsupport/src/malloc_walk.c
@@ -1,6 +1,11 @@
-/*
- *  malloc_walk Implementation
+/**
+ *  @file
  *
+ *  @brief Malloc Walk
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/mknod.c b/cpukit/libcsupport/src/mknod.c
index 6a63455d81..0a639f0813 100644
--- a/cpukit/libcsupport/src/mknod.c
+++ b/cpukit/libcsupport/src/mknod.c
@@ -1,10 +1,11 @@
-/*
- *  mknod()
- *
- *  This routine is not defined in the POSIX 1003.1b standard but is
- *  commonly supported on most UNIX and POSIX systems.  It is the
- *  foundation for creating file system objects.
+/**
+ *  @file
  *
+ *  @brief Create a Special or Ordinary File 
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -55,6 +56,11 @@ int rtems_filesystem_mknod(
   return rv;
 }
 
+/**
+ * This routine is not defined in the POSIX 1003.1b standard but is
+ *  commonly supported on most UNIX and POSIX systems.  It is the
+ *  foundation for creating file system objects.
+ */
 int mknod( const char *path, mode_t mode, dev_t dev )
 {
   int rv = 0;
diff --git a/cpukit/libcsupport/src/newlibc_reent.c b/cpukit/libcsupport/src/newlibc_reent.c
index 91b5bde5c9..72aa7f592c 100644
--- a/cpukit/libcsupport/src/newlibc_reent.c
+++ b/cpukit/libcsupport/src/newlibc_reent.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Newlib Support
+ *  @ingroup libcsupport
+ */
+
 /*
  *  The license and distribution terms for this file may be
  *  found in the file LICENSE in this distribution or at
@@ -98,9 +105,7 @@ void newlib_begin_hook(rtems_tcb *current_task)
  *  Called when a task is deleted.
  *  Must restore the new lib reentrancy state for the new current
  *  task.
- *
  */
-
 int newlib_free_buffers(
   FILE *fp
 )
diff --git a/cpukit/libcsupport/src/readlink.c b/cpukit/libcsupport/src/readlink.c
index 2cafcca10d..4abc68a955 100644
--- a/cpukit/libcsupport/src/readlink.c
+++ b/cpukit/libcsupport/src/readlink.c
@@ -1,6 +1,11 @@
-/*
- *  readlink() - POSIX 1003.1b - X.X.X - XXX
+/**
+ *  @file
  *
+ *  @brief Read Value of a Symbolic Link 
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,6 +22,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b - X.X.X - XXX
+ */
 ssize_t readlink( const char *path, char *buf, size_t bufsize )
 {
   ssize_t rv = 0;
diff --git a/cpukit/libcsupport/src/setpgid.c b/cpukit/libcsupport/src/setpgid.c
index 3b2011abf1..f3251bcacd 100644
--- a/cpukit/libcsupport/src/setpgid.c
+++ b/cpukit/libcsupport/src/setpgid.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Set Process Group ID for Job Control 
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -6,10 +13,9 @@
 #include <errno.h>
 #include <rtems/seterr.h>
 
-/*
+/**
  *  4.3.3 Set Process Group ID for Job Control, P1003.1b-1993, p. 89
  */
-
 int setpgid(
   pid_t  pid __attribute__((unused)),
   pid_t  pgid __attribute__((unused))
diff --git a/cpukit/libcsupport/src/sup_fs_deviceio.c b/cpukit/libcsupport/src/sup_fs_deviceio.c
index 74f92cb44c..67e035301a 100644
--- a/cpukit/libcsupport/src/sup_fs_deviceio.c
+++ b/cpukit/libcsupport/src/sup_fs_deviceio.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS DeviceIO Support
+ *  @ingroup Device
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2012.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/libcsupport/src/sup_fs_eval_path_generic.c b/cpukit/libcsupport/src/sup_fs_eval_path_generic.c
index 27dd80145a..380e5a69ef 100644
--- a/cpukit/libcsupport/src/sup_fs_eval_path_generic.c
+++ b/cpukit/libcsupport/src/sup_fs_eval_path_generic.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS File System Eval Generic Path
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/tcgetpgrp.c b/cpukit/libcsupport/src/tcgetpgrp.c
index ae879b3287..3488db1d03 100644
--- a/cpukit/libcsupport/src/tcgetpgrp.c
+++ b/cpukit/libcsupport/src/tcgetpgrp.c
@@ -1,6 +1,11 @@
-/*
- *  tcgetprgrp() - POSIX 1003.1b 7.2.3 - Get Foreground Process Group ID
+/**
+ *  @file
  *
+ *  @brief Get Foreground Process Group ID
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,6 +23,9 @@
 #include <sys/types.h>
 #include <unistd.h>
 
+/**
+ *  POSIX 1003.1b 7.2.3 - Get Foreground Process Group ID
+ */
 pid_t tcgetpgrp(int fd __attribute__((unused)))
 {
   return getpid();
diff --git a/cpukit/libcsupport/src/tcsetattr.c b/cpukit/libcsupport/src/tcsetattr.c
index f0f3b55ecc..07a71ba7d0 100644
--- a/cpukit/libcsupport/src/tcsetattr.c
+++ b/cpukit/libcsupport/src/tcsetattr.c
@@ -1,6 +1,11 @@
-/*
- *  tcsetattr() - POSIX 1003.1b 7.2.1 - Get and Set State
+/**
+ *  @file
  *
+ *  @brief Get and Set State
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -26,6 +31,9 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
+/**
+ *  POSIX 1003.1b 7.2.1 - Get and Set State
+ */
 int tcsetattr(
   int             fd,
   int             opt,
diff --git a/cpukit/libcsupport/src/termios_baud2index.c b/cpukit/libcsupport/src/termios_baud2index.c
index f8454e6f1c..9ced4b20ba 100644
--- a/cpukit/libcsupport/src/termios_baud2index.c
+++ b/cpukit/libcsupport/src/termios_baud2index.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Convert Bxxx Constant to Index
+ *  @ingroup TermiostypesSupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/libcsupport/src/termios_num2baud.c b/cpukit/libcsupport/src/termios_num2baud.c
index dc31ca7fc4..186922f978 100644
--- a/cpukit/libcsupport/src/termios_num2baud.c
+++ b/cpukit/libcsupport/src/termios_num2baud.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Converts the Integral Baud to Termios Control Flag Representation
+ *  @ingroup TermiostypesSupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/libcsupport/src/termiosinitialize.c b/cpukit/libcsupport/src/termiosinitialize.c
index 428458cc1a..11a1ef365b 100644
--- a/cpukit/libcsupport/src/termiosinitialize.c
+++ b/cpukit/libcsupport/src/termiosinitialize.c
@@ -1,6 +1,11 @@
-/*
- *  Termios initialization routine
+/**
+ *  @file
  *
+ *  @brief Termios Initialization
+ *  @ingroup Termios
+ */
+
+/*
  *  Author:
  *    W. Eric Norum
  *    Saskatchewan Accelerator Laboratory
diff --git a/cpukit/libcsupport/src/truncate.c b/cpukit/libcsupport/src/truncate.c
index 5d58128dd3..654d99e4d9 100644
--- a/cpukit/libcsupport/src/truncate.c
+++ b/cpukit/libcsupport/src/truncate.c
@@ -1,10 +1,11 @@
-/*
- *  truncate() - Truncate a File to the Specified Length
- *
- *  This routine is not defined in the POSIX 1003.1b standard but is
- *  commonly supported on most UNIX and POSIX systems.  It is provided
- *  for compatibility.
+/**
+ *  @file
  *
+ *  @brief Truncate a File to the Specified Length
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,6 +22,11 @@
 #include <errno.h>
 #include <fcntl.h>
 
+/**
+ *  This routine is not defined in the POSIX 1003.1b standard but is
+ *  commonly supported on most UNIX and POSIX systems.  It is provided
+ *  for compatibility.
+ */
 int truncate(
   const char  *path,
   off_t        length