libcsupport: GCI Doxygen Task #7

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

20 files changed, 161 insertions, 55 deletions

diff --git a/cpukit/libcsupport/src/__usrenv.c b/cpukit/libcsupport/src/__usrenv.c
index 6a793755ab..a0d96cb7eb 100644
--- a/cpukit/libcsupport/src/__usrenv.c
+++ b/cpukit/libcsupport/src/__usrenv.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS File System Location Support
+ *  @ingroup LibIOInternal
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/libcsupport/src/assocnamebyremotebitfield.c b/cpukit/libcsupport/src/assocnamebyremotebitfield.c
index 0bc9111e0c..97876ea6ca 100644
--- a/cpukit/libcsupport/src/assocnamebyremotebitfield.c
+++ b/cpukit/libcsupport/src/assocnamebyremotebitfield.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Name by Remote Bitfield
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H
diff --git a/cpukit/libcsupport/src/base_fs.c b/cpukit/libcsupport/src/base_fs.c
index df1b516a67..33712a7862 100644
--- a/cpukit/libcsupport/src/base_fs.c
+++ b/cpukit/libcsupport/src/base_fs.c
@@ -1,6 +1,11 @@
-/*
- *  Base file system initialization
+/**
+ *  @file
  *
+ *  @brief Base File System Initialization
+ *  @ingroup LibIO
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,16 +29,6 @@
  *  Default mode for created files.
  */
 
-
-/*
- *  rtems_filesystem_initialize
- *
- *  Initialize the foundation of the file system.  This is specified
- *  by the structure rtems_filesystem_mount_table.  The usual
- *  configuration is a single instantiation of the IMFS or miniIMFS with
- *  a single "/dev" directory in it.
- */
-
 void rtems_filesystem_initialize( void )
 {
   int rv = 0;
diff --git a/cpukit/libcsupport/src/calloc.c b/cpukit/libcsupport/src/calloc.c
index 88928cca19..279c16c7be 100644
--- a/cpukit/libcsupport/src/calloc.c
+++ b/cpukit/libcsupport/src/calloc.c
@@ -1,6 +1,11 @@
-/*
- *  calloc()
+/**
+ *  @file
  *
+ *  @brief Allocate Space for Array in Memory
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/cfsetispeed.c b/cpukit/libcsupport/src/cfsetispeed.c
index 571407d0f7..d4cce532e8 100644
--- a/cpukit/libcsupport/src/cfsetispeed.c
+++ b/cpukit/libcsupport/src/cfsetispeed.c
@@ -1,6 +1,11 @@
-/*
- *  cfsetispeed() - POSIX 1003.1b 7.1.3 - Baud Rate Functions
+/**
+ *  @file
  *
+ *  @brief Baud Rate Functions
+ *  @ingroup Termios
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,6 +29,9 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
+/**
+ *  POSIX 1003.1b 7.1.3 - Baud Rate Functions
+ */
 int cfsetispeed(
   struct termios *tp,
   speed_t         speed
diff --git a/cpukit/libcsupport/src/cfsetospeed.c b/cpukit/libcsupport/src/cfsetospeed.c
index 850f4bbdb0..a6b4d4b6ee 100644
--- a/cpukit/libcsupport/src/cfsetospeed.c
+++ b/cpukit/libcsupport/src/cfsetospeed.c
@@ -1,6 +1,11 @@
-/*
- *  cfsetospeed() - POSIX 1003.1b 7.1.3 - Baud Rate Functions
+/**
+ *  @file
  *
+ *  @brief Baud Rate Functions
+ *  @ingroup Termios
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,6 +29,9 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
+/**
+ *  POSIX 1003.1b 7.1.3 - Baud Rate Functions
+ */
 int cfsetospeed(
   struct termios *tp,
   speed_t         speed
diff --git a/cpukit/libcsupport/src/fchmod.c b/cpukit/libcsupport/src/fchmod.c
index 944873817d..94e82647fc 100644
--- a/cpukit/libcsupport/src/fchmod.c
+++ b/cpukit/libcsupport/src/fchmod.c
@@ -1,6 +1,11 @@
-/*
- *  fchmod() - POSIX 1003.1b 5.6.4 - Change File Modes
+/**
+ *  @file
  *
+ *  @brief Change File Modes
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,6 +22,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.6.4 - Change File Modes
+ */
 int fchmod( int fd, mode_t mode )
 {
   int rv;
diff --git a/cpukit/libcsupport/src/getegid.c b/cpukit/libcsupport/src/getegid.c
index 222942066b..9ec6f0b6fc 100644
--- a/cpukit/libcsupport/src/getegid.c
+++ b/cpukit/libcsupport/src/getegid.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get Real User, Effective User, Ral Group, and Effective Group IDs
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -9,11 +16,10 @@
 #include <rtems/seterr.h>
 #include <rtems/userenv.h>
 
-/*
+/**
  *  4.2.1 Get Real User, Effective User, Ral Group, and Effective Group IDs,
  *        P1003.1b-1993, p. 84
  */
-
 gid_t getegid( void )
 {
   return _POSIX_types_Egid;
diff --git a/cpukit/libcsupport/src/getuid.c b/cpukit/libcsupport/src/getuid.c
index 6c4dbf0bb7..f01c163caf 100644
--- a/cpukit/libcsupport/src/getuid.c
+++ b/cpukit/libcsupport/src/getuid.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get Real User, Effective User, Ral Group, and Effective Group IDs
+ *  @ingroup libcsupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
@@ -15,7 +22,7 @@
 
 #include <rtems/userenv.h>
 
-/*
+/**
  *  4.2.1 Get Real User, Effective User, Ral Group, and Effective Group IDs,
  *        P1003.1b-1993, p. 84
  */
diff --git a/cpukit/libcsupport/src/malloc.c b/cpukit/libcsupport/src/malloc.c
index dea6f8f3c7..f79e3bb4f7 100644
--- a/cpukit/libcsupport/src/malloc.c
+++ b/cpukit/libcsupport/src/malloc.c
@@ -1,7 +1,11 @@
-/*
- *  RTEMS Malloc Family Implementation
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Malloc Family Implementation
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/malloc_deferred.c b/cpukit/libcsupport/src/malloc_deferred.c
index 28c6379b86..d1ad56f64b 100644
--- a/cpukit/libcsupport/src/malloc_deferred.c
+++ b/cpukit/libcsupport/src/malloc_deferred.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Malloc Deferred Support
+ *  @ingroup libcsupport
+ */
+
 /*
  *  Process free requests deferred because they were from ISR
  *  or other critical section.
diff --git a/cpukit/libcsupport/src/mallocsetheapptr.c b/cpukit/libcsupport/src/mallocsetheapptr.c
index 42e887810d..414918a4b5 100644
--- a/cpukit/libcsupport/src/mallocsetheapptr.c
+++ b/cpukit/libcsupport/src/mallocsetheapptr.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Malloc Set Heap Pointer -- Primarily for Debug
+/**
+ *  @file
  *
+ *  @brief RTEMS Malloc Set Heap Pointer
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/mkfifo.c b/cpukit/libcsupport/src/mkfifo.c
index 2ed351fe9d..ac4bb40cae 100644
--- a/cpukit/libcsupport/src/mkfifo.c
+++ b/cpukit/libcsupport/src/mkfifo.c
@@ -1,6 +1,11 @@
-/*
- *  mkfifo() - POSIX 1003.1b 5.4.1 - Make a FIFO Special File
+/**
+ *  @file
  *
+ *  @brief Make a FIFO Special File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,6 +22,9 @@
 #include <sys/stat.h>
 #include <errno.h>
 
+/**
+ *  POSIX 1003.1b 5.4.1 - Make a FIFO Special File
+ */
 int mkfifo(
   const  char *path,
   mode_t       mode
diff --git a/cpukit/libcsupport/src/open.c b/cpukit/libcsupport/src/open.c
index 02436b66e7..ead76a6fa3 100644
--- a/cpukit/libcsupport/src/open.c
+++ b/cpukit/libcsupport/src/open.c
@@ -1,6 +1,11 @@
-/*
- *  open() - POSIX 1003.1 5.3.1 - Open a File
+/**
+ *  @file
  *
+ *  @brief Open a File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -120,6 +125,9 @@ static int do_open(
   return rv;
 }
 
+/**
+*  POSIX 1003.1 5.3.1 - Open a File
+*/
 int open( const char *path, int oflag, ... )
 {
   int rv = 0;
@@ -144,16 +152,15 @@ int open( const char *path, int oflag, ... )
   return rv;
 }
 
-/*
- *  _open_r
- *
- *  This is the Newlib dependent reentrant version of open().
- */
+
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE__OPEN_R)
 
 #include <reent.h>
 
+/**
+ *  This is the Newlib dependent reentrant version of open().
+ */
 int _open_r(
   struct _reent *ptr __attribute__((unused)),
   const char    *buf,
diff --git a/cpukit/libcsupport/src/readdir_r.c b/cpukit/libcsupport/src/readdir_r.c
index 28c6dadfe0..ba0e53af92 100644
--- a/cpukit/libcsupport/src/readdir_r.c
+++ b/cpukit/libcsupport/src/readdir_r.c
@@ -1,5 +1,8 @@
-/*
- *  readdir_r - reentrant version of readdir()
+/**
+ *  @file
+ *
+ *  @brief Read a Directory
+ *  @ingroup libcsupport
  */
 
 #if HAVE_CONFIG_H
@@ -13,10 +16,10 @@
 #include <errno.h>
 #include <stdio.h>
 
-/*
- * The RTEMS version of readdir is already thread-safe.
+/**
+ *  The RTEMS version of readdir is already thread-safe.
+ *  This routine is reentrant version of readdir().
  */
-
 int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result)
 {
      *result = readdir(dirp);
diff --git a/cpukit/libcsupport/src/setegid.c b/cpukit/libcsupport/src/setegid.c
index d19ced41f9..249491102b 100644
--- a/cpukit/libcsupport/src/setegid.c
+++ b/cpukit/libcsupport/src/setegid.c
@@ -25,7 +25,7 @@
 #include <rtems/seterr.h>
 #include <rtems/userenv.h>
 
-/*
+/**
  *  4.2.1 Get Real User, Effective User, Ral Group, and Effective Group IDs,
  *        P1003.1b-1993, p. 84
  */
diff --git a/cpukit/libcsupport/src/strlcat.c b/cpukit/libcsupport/src/strlcat.c
index b617cb93e8..6ca17b9d40 100644
--- a/cpukit/libcsupport/src/strlcat.c
+++ b/cpukit/libcsupport/src/strlcat.c
@@ -1,6 +1,11 @@
-/*
- * utils.c - various utility functions used in pppd.
+/**
+ *  @file
  *
+ *  @brief Concatenate a Strings
+ *  @ingroup libcsupport
+ */
+
+/*
  * Copyright (c) 1999 The Australian National University.
  * All rights reserved.
  *
@@ -24,9 +29,10 @@
 #include <string.h>
 
 #ifndef HAVE_STRLCAT
-/*
- * strlcat - like strcat/strncat, doesn't overflow destination buffer,
- * always leaves destination null-terminated (for len > 0).
+
+/**
+ *  like strcat/strncat, doesn't overflow destination buffer,
+ *  always leaves destination null-terminated (for len > 0).
  */
 size_t
 strlcat(
diff --git a/cpukit/libcsupport/src/sup_fs_exist_in_same_instance.c b/cpukit/libcsupport/src/sup_fs_exist_in_same_instance.c
index 6d19ae4346..adb3d9ba1d 100644
--- a/cpukit/libcsupport/src/sup_fs_exist_in_same_instance.c
+++ b/cpukit/libcsupport/src/sup_fs_exist_in_same_instance.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Checks that the Locations Exist in the Same File System Instance
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/tcflow.c b/cpukit/libcsupport/src/tcflow.c
index edd056952f..c445ffb04f 100644
--- a/cpukit/libcsupport/src/tcflow.c
+++ b/cpukit/libcsupport/src/tcflow.c
@@ -1,6 +1,11 @@
-/*
- *  tcflow() - POSIX 1003.1b 7.2.2 - Line Control Functions
+/**
+ *  @file
  *
+ *  @brief Line Control Functions
+ *  @ingroup Termios
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/umask.c b/cpukit/libcsupport/src/umask.c
index d9b5580dba..1a5daa51cd 100644
--- a/cpukit/libcsupport/src/umask.c
+++ b/cpukit/libcsupport/src/umask.c
@@ -1,6 +1,11 @@
-/*
- *  umask() - POSIX 1003.1b 5.3.3 - Set File Creation Mask
+/**
+ *  @file
  *
+ *  @brief Set File Creation Mask
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,6 +24,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.3.3 - Set File Creation Mask
+ */
 mode_t umask( mode_t cmask )
 {
   mode_t old_mask;