libcsupport: Doxygen Enhancement Task #8

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

20 files changed, 177 insertions, 100 deletions

diff --git a/cpukit/libcsupport/src/__gettod.c b/cpukit/libcsupport/src/__gettod.c
index a2f9d1052d..73cd04f821 100644
--- a/cpukit/libcsupport/src/__gettod.c
+++ b/cpukit/libcsupport/src/__gettod.c
@@ -1,6 +1,11 @@
-/*
- *  gettimeofday() - SVR4 and BSD4.3 extension required by Newlib
+/**
+ *  @file
  *
+ *  @brief Get the Date and Time
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -22,8 +27,11 @@
 #include <rtems/seterr.h>
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE_GETTIMEOFDAY)
-/*
- *  NOTE:  The solaris gettimeofday does not have a second parameter.
+
+/** 
+ *  SVR4 and BSD4.3 extension required by Newlib
+ * 
+ *  @note The solaris gettimeofday does not have a second parameter.
  */
 int gettimeofday(
   struct timeval  *tp,
@@ -54,7 +62,7 @@ int gettimeofday(
 
 #include <sys/reent.h>
 
-/*
+/**
  *  "Reentrant" version
  */
 int _gettimeofday_r(
@@ -68,10 +76,10 @@ int _gettimeofday_r(
 #endif
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE__GETTIMEOFDAY)
-/*
+
+/**
  *  "System call" version
  */
-
 int _gettimeofday(
   struct timeval  *tp,
   struct timezone *tzp
diff --git a/cpukit/libcsupport/src/__times.c b/cpukit/libcsupport/src/__times.c
index 097cc9fe63..d941f933db 100644
--- a/cpukit/libcsupport/src/__times.c
+++ b/cpukit/libcsupport/src/__times.c
@@ -1,6 +1,11 @@
-/*
- *  times() - POSIX 1003.1b 4.5.2 - Get Process Times
+/**
+ *  @file
  *
+ *  @brief Get Process Times
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,6 +29,9 @@
   #include <rtems/score/timestamp.h>
 #endif
 
+/**
+ *  POSIX 1003.1b 4.5.2 - Get Process Times
+ */
 clock_t _times(
    struct tms  *ptms
 )
@@ -79,12 +87,9 @@ clock_t _times(
   return ticks;
 } 
 
-/*
- *  times()
- *
+/**
  *  times() system call wrapper for _times() above.
  */
-
 clock_t times(
    struct tms  *ptms
 )
@@ -92,16 +97,13 @@ clock_t times(
   return _times( ptms );
 }
 
-/*
- *  _times_r
- *
- *  This is the Newlib dependent reentrant version of times().
- */
-
 #if defined(RTEMS_NEWLIB)
 
 #include <reent.h>
 
+/**
+ *  This is the Newlib dependent reentrant version of times().
+ */
 clock_t _times_r(
    struct _reent *ptr __attribute__((unused)),
    struct tms  *ptms
diff --git a/cpukit/libcsupport/src/assocnamebyremote.c b/cpukit/libcsupport/src/assocnamebyremote.c
index 92bad05956..376ba47ac7 100644
--- a/cpukit/libcsupport/src/assocnamebyremote.c
+++ b/cpukit/libcsupport/src/assocnamebyremote.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Name by Remote
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H
diff --git a/cpukit/libcsupport/src/cfgetispeed.c b/cpukit/libcsupport/src/cfgetispeed.c
index 390e607ae5..a458f26b39 100644
--- a/cpukit/libcsupport/src/cfgetispeed.c
+++ b/cpukit/libcsupport/src/cfgetispeed.c
@@ -1,6 +1,11 @@
-/*
- *  cfgetispeed() - 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).
  *
diff --git a/cpukit/libcsupport/src/freenode.c b/cpukit/libcsupport/src/freenode.c
index 84e58256d2..1646352359 100644
--- a/cpukit/libcsupport/src/freenode.c
+++ b/cpukit/libcsupport/src/freenode.c
@@ -1,6 +1,10 @@
-/*
- *  freenode()
+/**
+ *  @file
  *
+ *  @brief Releases all Resources of a Location
+ *  @ingroup LibIOInternal
+ */
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/getchark.c b/cpukit/libcsupport/src/getchark.c
index 1e7bf017c8..785096905b 100644
--- a/cpukit/libcsupport/src/getchark.c
+++ b/cpukit/libcsupport/src/getchark.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get Character from Stdin
+ *  @ingroup libcsupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/libcsupport/src/getlogin.c b/cpukit/libcsupport/src/getlogin.c
index dbc348b95f..fe0f9ad6f8 100644
--- a/cpukit/libcsupport/src/getlogin.c
+++ b/cpukit/libcsupport/src/getlogin.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get User Name
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -15,10 +22,10 @@
 #include <unistd.h>
 #include <pwd.h>
 
-/*
+/**
  *  4.2.4 Get User Name, P1003.1b-1993, p. 87
  *
- *  NOTE:  P1003.1c/D10, p. 49 adds getlogin_r().
+ *  @note P1003.1c/D10, p. 49 adds getlogin_r().
  */
 char *getlogin( void )
 {
@@ -26,10 +33,10 @@ char *getlogin( void )
   return _POSIX_types_Getlogin_buffer;
 }
 
-/*
+/**
  *  4.2.4 Get User Name, P1003.1b-1993, p. 87
  *
- *  NOTE:  P1003.1c/D10, p. 49 adds getlogin_r().
+ *  @note P1003.1c/D10, p. 49 adds getlogin_r().
  */
 int getlogin_r(
   char   *name,
diff --git a/cpukit/libcsupport/src/libio.c b/cpukit/libcsupport/src/libio.c
index c8ab1f3a9a..a12a12c833 100644
--- a/cpukit/libcsupport/src/libio.c
+++ b/cpukit/libcsupport/src/libio.c
@@ -1,8 +1,11 @@
-/*
- *  This file contains the support infrastructure used to manage the
- *  table of integer style file descriptors used by the low level
- *  POSIX system calls like open(), read, fstat(), etc.
+/**
+ *  @file
  *
+ *  @brief File Descriptor Routines
+ *  @ingroup LibIOInternal
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -39,12 +42,6 @@
  */
 #undef ACCEPT_O_NDELAY_ALIAS
 
-/*
- *  rtems_libio_fcntl_flags
- *
- *  Convert UNIX fnctl(2) flags to ones that RTEMS drivers understand
- */
-
 static const rtems_assoc_t access_modes_assoc[] = {
   { "READ",       LIBIO_FLAGS_READ,  O_RDONLY },
   { "WRITE",      LIBIO_FLAGS_WRITE, O_WRONLY },
@@ -87,12 +84,6 @@ uint32_t rtems_libio_fcntl_flags( int fcntl_flags )
   return flags;
 }
 
-/*
- *  rtems_libio_to_fcntl_flags
- *
- *  Convert RTEMS internal flags to UNIX fnctl(2) flags
- */
-
 int rtems_libio_to_fcntl_flags( uint32_t flags )
 {
   int fcntl_flags = 0;
@@ -120,13 +111,6 @@ int rtems_libio_to_fcntl_flags( uint32_t flags )
   return fcntl_flags;
 }
 
-/*
- *  rtems_libio_allocate
- *
- *  This routine searches the IOP Table for an unused entry.  If it
- *  finds one, it returns it.  Otherwise, it returns NULL.
- */
-
 rtems_libio_t *rtems_libio_allocate( void )
 {
   rtems_libio_t *iop = NULL;
@@ -145,13 +129,6 @@ rtems_libio_t *rtems_libio_allocate( void )
   return iop;
 }
 
-/*
- *  rtems_libio_free
- *
- *  This routine frees the resources associated with an IOP (file descriptor)
- *  and clears the slot in the IOP Table.
- */
-
 void rtems_libio_free(
   rtems_libio_t *iop
 )
diff --git a/cpukit/libcsupport/src/libio_init.c b/cpukit/libcsupport/src/libio_init.c
index 9e767c58b0..3496b59b5e 100644
--- a/cpukit/libcsupport/src/libio_init.c
+++ b/cpukit/libcsupport/src/libio_init.c
@@ -1,8 +1,11 @@
-/*
- *  This file contains the support infrastructure used to manage the
- *  table of integer style file descriptors used by the low level
- *  POSIX system calls like open(), read, fstat(), etc.
+/**
+ *  @file
  *
+ *  @brief RTEMS LibIO Initialization
+ *  @ingroup LibIO
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -38,12 +41,6 @@ rtems_id           rtems_libio_semaphore;
 rtems_libio_t     *rtems_libio_iops;
 rtems_libio_t     *rtems_libio_iop_freelist;
 
-/*
- *  rtems_libio_init
- *
- *  Called by BSP startup code to initialize the libio subsystem.
- */
-
 void rtems_libio_init( void )
 {
     rtems_status_code rc;
diff --git a/cpukit/libcsupport/src/malloc_dirtier.c b/cpukit/libcsupport/src/malloc_dirtier.c
index 122c230c08..68ad153d49 100644
--- a/cpukit/libcsupport/src/malloc_dirtier.c
+++ b/cpukit/libcsupport/src/malloc_dirtier.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Malloc Family -- Dirty Memory from Malloc
+/**
+ *  @file
  *
+ *  @brief Dirty Memory Function
+ *  @ingroup MallocSupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/malloc_get_statistics.c b/cpukit/libcsupport/src/malloc_get_statistics.c
index 0d9269d7a4..187d5ceea1 100644
--- a/cpukit/libcsupport/src/malloc_get_statistics.c
+++ b/cpukit/libcsupport/src/malloc_get_statistics.c
@@ -1,6 +1,11 @@
-/*
- *  malloc_get_statistics Implementation
+/**
+ *  @file
  *
+ *  @brief Print Malloc Statistic Usage Report
+ *  @ingroup MallocSupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/mallocfreespace.c b/cpukit/libcsupport/src/mallocfreespace.c
index c67896dbb2..2b262ca272 100644
--- a/cpukit/libcsupport/src/mallocfreespace.c
+++ b/cpukit/libcsupport/src/mallocfreespace.c
@@ -1,7 +1,11 @@
-/*
- *  RTEMS Malloc Get Free Information
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Malloc Get Free Information
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/readv.c b/cpukit/libcsupport/src/readv.c
index 4e540d5da4..2ff7f63767 100644
--- a/cpukit/libcsupport/src/readv.c
+++ b/cpukit/libcsupport/src/readv.c
@@ -1,10 +1,11 @@
-/*
- *  readv() - POSIX 1003.1 - Read a Vector
- *
- *  OpenGroup URL:
- *
- *  http://www.opengroup.org/onlinepubs/009695399/functions/readv.html
+/**
+ *  @file
  *
+ *  @brief Read a Vector
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,6 +24,13 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
+/**
+ *  readv() - POSIX 1003.1 - Read a Vector
+ *
+ *  OpenGroup URL:
+ *
+ *  http://www.opengroup.org/onlinepubs/009695399/functions/readv.html
+ */
 ssize_t readv(
   int                 fd,
   const struct iovec *iov,
diff --git a/cpukit/libcsupport/src/setsid.c b/cpukit/libcsupport/src/setsid.c
index e77179d64f..f86b9e2b6a 100644
--- a/cpukit/libcsupport/src/setsid.c
+++ b/cpukit/libcsupport/src/setsid.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Create Session and Set Process Group ID
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -6,10 +13,9 @@
 
 #include <rtems/seterr.h>
 
-/*
+/**
  *  4.3.2 Create Session and Set Process Group ID, P1003.1b-1993, p. 88
  */
-
 pid_t setsid( void )
 {
   rtems_set_errno_and_return_minus_one( EPERM );
diff --git a/cpukit/libcsupport/src/stat.c b/cpukit/libcsupport/src/stat.c
index 06c3a22b52..e75fdca171 100644
--- a/cpukit/libcsupport/src/stat.c
+++ b/cpukit/libcsupport/src/stat.c
@@ -1,8 +1,11 @@
-/*
- *  stat() - POSIX 1003.1b 5.6.2 - Get File Status
- *
- *  Reused from lstat().
+/**
+ *  @file
  *
+ *  @brief Get File Status
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -31,6 +34,11 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.6.2 - Get File Status
+ * 
+ *  Reused from lstat().
+ */
 int _STAT_NAME( const char *path, struct stat *buf )
 {
   int rv = 0;
@@ -48,16 +56,13 @@ int _STAT_NAME( const char *path, struct stat *buf )
   return rv;
 }
 
-/*
- *  _stat_r, _lstat_r
- *
- *  This is the Newlib dependent reentrant version of stat() and lstat().
- */
-
 #if defined(RTEMS_NEWLIB)
 
 #include <reent.h>
 
+/**
+ *  This is the Newlib dependent reentrant version of stat() and lstat().
+ */
 int _STAT_R_NAME(
   struct _reent *ptr __attribute__((unused)),
   const char    *path,
diff --git a/cpukit/libcsupport/src/sup_fs_check_permissions.c b/cpukit/libcsupport/src/sup_fs_check_permissions.c
index 85d237cce6..1bcc5d918e 100644
--- a/cpukit/libcsupport/src/sup_fs_check_permissions.c
+++ b/cpukit/libcsupport/src/sup_fs_check_permissions.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS File System Permissions Check Support
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/sup_fs_location.c b/cpukit/libcsupport/src/sup_fs_location.c
index 8bf0374323..2ce514549e 100644
--- a/cpukit/libcsupport/src/sup_fs_location.c
+++ b/cpukit/libcsupport/src/sup_fs_location.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS File System Location Support
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/termios_setinitialbaud.c b/cpukit/libcsupport/src/termios_setinitialbaud.c
index 072a7bda24..cba49b4590 100644
--- a/cpukit/libcsupport/src/termios_setinitialbaud.c
+++ b/cpukit/libcsupport/src/termios_setinitialbaud.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Sets the Initial Baud in the Termios Context
+ *  @ingroup TermiostypesSupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/libcsupport/src/ttyname.c b/cpukit/libcsupport/src/ttyname.c
index 2e76597d96..f136e89a17 100644
--- a/cpukit/libcsupport/src/ttyname.c
+++ b/cpukit/libcsupport/src/ttyname.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Demetermine Terminal Device Name
+ *  @ingroup libcsupport
+ */
+
 /*
  * Copyright (c) 1988, 1993
  *	The Regents of the University of California.  All rights reserved.
@@ -54,7 +61,7 @@
 
 static char ttyname_buf[sizeof (_PATH_DEV) + MAXNAMLEN];
 
-/*
+/**
  *  ttyname_r() - POSIX 1003.1b 4.7.2 - Demetermine Terminal Device Name
  */
 int ttyname_r(
@@ -99,10 +106,9 @@ int ttyname_r(
   return 0;
 }
 
-/*
+/**
  *  ttyname() - POSIX 1003.1b 4.7.2 - Determine Terminal Device Name
  */
-
 char *ttyname(
   int fd
 )
diff --git a/cpukit/libcsupport/src/utime.c b/cpukit/libcsupport/src/utime.c
index 0f65397166..0b60de6013 100644
--- a/cpukit/libcsupport/src/utime.c
+++ b/cpukit/libcsupport/src/utime.c
@@ -1,6 +1,11 @@
-/*
- *  utime() - POSIX 1003.1b 5.5.6 - Set File Access and Modification Times
+/**
+ *  @file
  *
+ *  @brief Set File Access and Modification Times
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,6 +25,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.5.6 - Set File Access and Modification Times
+ */
 int utime( const char *path, const struct utimbuf *times )
 {
   int rv = 0;