libcsupport: Doxygen Enhancement Task #3

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

25 files changed, 225 insertions, 39 deletions

diff --git a/cpukit/libcsupport/include/rtems/assoc.h b/cpukit/libcsupport/include/rtems/assoc.h
index f55d3fe376..80a2fe7cdf 100644
--- a/cpukit/libcsupport/include/rtems/assoc.h
+++ b/cpukit/libcsupport/include/rtems/assoc.h
@@ -9,6 +9,11 @@
 #ifndef _RTEMS_RTEMS_ASSOC_H
 #define _RTEMS_RTEMS_ASSOC_H
 
+/**
+ *  @defgroup Associativity Routines
+ */
+/**@{*/
+
 #include <stdint.h> /* uint32_t */
 
 #ifdef __cplusplus
@@ -51,6 +56,10 @@ uint32_t rtems_assoc_remote_by_name(
   const rtems_assoc_t *,
   const char *
 );
+
+/**
+ *  @brief RTEMS Associate Local by Name
+ */
 uint32_t rtems_assoc_local_by_name(
   const rtems_assoc_t *,
   const char *
@@ -66,6 +75,9 @@ const char *rtems_assoc_name_by_remote(
   uint32_t
 );
 
+/**
+ *  @brief RTEMS Assoc Routines
+ */
 uint32_t rtems_assoc_remote_by_local_bitfield(
   const rtems_assoc_t *,
   uint32_t
@@ -111,5 +123,5 @@ const char *rtems_assoc_name_bad(
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif /* ! _RTEMS_RTEMS_ASSOC_H */
diff --git a/cpukit/libcsupport/include/rtems/deviceio.h b/cpukit/libcsupport/include/rtems/deviceio.h
index d1d37fdfd1..637eef4f6c 100644
--- a/cpukit/libcsupport/include/rtems/deviceio.h
+++ b/cpukit/libcsupport/include/rtems/deviceio.h
@@ -1,3 +1,7 @@
+/**
+ * @file rtems/deviceio.h
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2012.
  *  On-Line Applications Research Corporation (OAR).
@@ -10,12 +14,25 @@
 #ifndef _RTEMS_DEVICEIO_H
 #define _RTEMS_DEVICEIO_H
 
+/**
+ *  @defgroup Device IO Handler
+ */
+/**@{*/
+
 #include <rtems/libio.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ *  @brief IMFS Device Node Handlers
+ *
+ *  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.
+ */
 int rtems_deviceio_errno( rtems_status_code status );
 
 int rtems_deviceio_open(
@@ -59,6 +76,8 @@ int rtems_deviceio_control(
 
 #ifdef __cplusplus
 }
-#endif /* __cplusplus */
+#endif
+/**@}*/
+/* __cplusplus */
 
 #endif /* _RTEMS_DEVICEIO_H */
diff --git a/cpukit/libcsupport/include/rtems/libio.h b/cpukit/libcsupport/include/rtems/libio.h
index 9374f3ac1a..7281765a0a 100644
--- a/cpukit/libcsupport/include/rtems/libio.h
+++ b/cpukit/libcsupport/include/rtems/libio.h
@@ -46,6 +46,7 @@ extern "C" {
  *
  * @{
  */
+/**@{*/
 
 /**
  * @brief File system node types.
diff --git a/cpukit/libcsupport/include/rtems/libio_.h b/cpukit/libcsupport/include/rtems/libio_.h
index 4f7a432e9a..941efb785b 100644
--- a/cpukit/libcsupport/include/rtems/libio_.h
+++ b/cpukit/libcsupport/include/rtems/libio_.h
@@ -19,6 +19,11 @@
 #ifndef _RTEMS_RTEMS_LIBIO__H
 #define _RTEMS_RTEMS_LIBIO__H
 
+/**
+ *  @defgroup libio Internal Interface
+ */
+/**@{*/
+
 #include <errno.h>
 
 #include <rtems.h>
@@ -536,6 +541,9 @@ int rtems_filesystem_mknod(
   dev_t dev
 );
 
+/**
+ *  @brief POSIX 1003.1b - 5.2.1 - Change Current Working Directory
+ */
 int rtems_filesystem_chdir( rtems_filesystem_location_info_t *loc );
 
 int rtems_filesystem_chown(
@@ -803,6 +811,6 @@ static inline bool rtems_filesystem_is_parent_directory(
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /* end of include file */
diff --git a/cpukit/libcsupport/include/sys/utsname.h b/cpukit/libcsupport/include/sys/utsname.h
index ca9e18e799..a56d74abfd 100644
--- a/cpukit/libcsupport/include/sys/utsname.h
+++ b/cpukit/libcsupport/include/sys/utsname.h
@@ -16,6 +16,11 @@
 #ifndef __POSIX_SYS_UTSNAME_h
 #define __POSIX_SYS_UTSNAME_h
 
+/**
+ *  @defgroup utsname Service
+ */
+/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -47,10 +52,9 @@ struct utsname {
                            /*   is running */
 };
 
-/*
- *  4.4.1 Get System Name, P1003.1b-1993, p. 90
+/**
+ * @brief 4.4.1 Get System Name, P1003.1b-1993, p. 90
  */
-
 int uname(
   struct utsname *name
 );
@@ -58,5 +62,6 @@ int uname(
 #ifdef __cplusplus
 }
 #endif
+/**@}*/
 #endif
 /* end of include file */
diff --git a/cpukit/libcsupport/src/_realloc_r.c b/cpukit/libcsupport/src/_realloc_r.c
index 663812ea12..1dcc44178f 100644
--- a/cpukit/libcsupport/src/_realloc_r.c
+++ b/cpukit/libcsupport/src/_realloc_r.c
@@ -1,6 +1,11 @@
-/*
- *  _realloc_r Implementation
+/**
+ * @file
  *
+ * @brief  _realloc_r Implementation
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/access.c b/cpukit/libcsupport/src/access.c
index 3319774e36..5013be53b3 100644
--- a/cpukit/libcsupport/src/access.c
+++ b/cpukit/libcsupport/src/access.c
@@ -1,6 +1,11 @@
-/*
- *  access() - POSIX 1003.1b 5.6.3 - File Accessibility
+/**
+ * @file
  *
+ * @brief access() - POSIX 1003.1b 5.6.3 - File Accessibility
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/assoclocalbyname.c b/cpukit/libcsupport/src/assoclocalbyname.c
index ed2d4cdce2..082ee6d812 100644
--- a/cpukit/libcsupport/src/assoclocalbyname.c
+++ b/cpukit/libcsupport/src/assoclocalbyname.c
@@ -1,6 +1,17 @@
+/**
+ * @file
+ *
+ * @brief RTEMS Associate Local by Name
+ * @ingroup Associativity Routines
+ */
+
 /*
- * assoc.c
- *      rtems assoc routines
+ *  COPYRIGHT (c) 1989-2008.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  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
diff --git a/cpukit/libcsupport/src/assocremotebylocalbitfield.c b/cpukit/libcsupport/src/assocremotebylocalbitfield.c
index 42c5d14963..bc2e98306d 100644
--- a/cpukit/libcsupport/src/assocremotebylocalbitfield.c
+++ b/cpukit/libcsupport/src/assocremotebylocalbitfield.c
@@ -1,6 +1,17 @@
+/**
+ * @file
+ *
+ * @brief RTEMS Assoc Routines
+ * @ingroup Associativity Routines
+ */
+
 /*
- * assoc.c
- *      rtems assoc routines
+ *  COPYRIGHT (c) 1989-2008.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  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
diff --git a/cpukit/libcsupport/src/chdir.c b/cpukit/libcsupport/src/chdir.c
index 88e9fcae68..9c49b9ee5e 100644
--- a/cpukit/libcsupport/src/chdir.c
+++ b/cpukit/libcsupport/src/chdir.c
@@ -1,6 +1,11 @@
-/*
- *  chdir() - POSIX 1003.1b - 5.2.1 - Change Current Working Directory
+/**
+ * @file
  *
+ * @brief POSIX 1003.1b - 5.2.1 - Change Current Working Directory
+ * @ingroup libio Internal Interface
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/chroot.c b/cpukit/libcsupport/src/chroot.c
index 9e63704f95..36f0eaa536 100644
--- a/cpukit/libcsupport/src/chroot.c
+++ b/cpukit/libcsupport/src/chroot.c
@@ -1,5 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Change Root Directory
+ * @ingroup libcsupport
+ */
+
 /*
- *  chroot() -  Change Root Directory
  *  Author: fernando.ruiz@ctv.es
  *
  *  COPYRIGHT (c) 1989-2008.
diff --git a/cpukit/libcsupport/src/close.c b/cpukit/libcsupport/src/close.c
index 2e6279dfd3..9b86d04d05 100644
--- a/cpukit/libcsupport/src/close.c
+++ b/cpukit/libcsupport/src/close.c
@@ -1,6 +1,11 @@
-/*
- *  close() - POSIX 1003.1b 6.3.1 - Close a File
+/**
+ * @file
  *
+ * @brief POSIX 1003.1b 6.3.1 - Close a File
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/dup.c b/cpukit/libcsupport/src/dup.c
index 324659f544..ddfc425b13 100644
--- a/cpukit/libcsupport/src/dup.c
+++ b/cpukit/libcsupport/src/dup.c
@@ -1,6 +1,11 @@
-/*
- *  dup() - POSIX 1003.1b 6.2.1 Duplicate an Open File Descriptor
+/**
+ * @file
  *
+ * @brief POSIX 1003.1b 6.2.1 Duplicate an Open File Descriptor
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/fcntl.c b/cpukit/libcsupport/src/fcntl.c
index ca04a0c20f..53feb669b1 100644
--- a/cpukit/libcsupport/src/fcntl.c
+++ b/cpukit/libcsupport/src/fcntl.c
@@ -1,6 +1,11 @@
-/*
- *   fcntl() - POSIX 1003.1b 6.5.2 - File Control
+/**
+ * @file
  *
+ * @brief POSIX 1003.1b 6.5.2 - File Control
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/fdatasync.c b/cpukit/libcsupport/src/fdatasync.c
index 3fd84df80e..91ec9da7b0 100644
--- a/cpukit/libcsupport/src/fdatasync.c
+++ b/cpukit/libcsupport/src/fdatasync.c
@@ -1,6 +1,11 @@
-/*
- *  fdatasync() - POSIX 1003.1b 6.6.2 - Synchronize the Data of a File
+/**
+ * @file
  *
+ * @brief POSIX 1003.1b 6.6.2 - Synchronize the Data of a File
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/free.c b/cpukit/libcsupport/src/free.c
index 1e29d74e80..4e31555a5e 100644
--- a/cpukit/libcsupport/src/free.c
+++ b/cpukit/libcsupport/src/free.c
@@ -1,6 +1,11 @@
-/*
- *  calloc()
+/**
+ * @file
  *
+ * @brief calloc()
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/getcwd.c b/cpukit/libcsupport/src/getcwd.c
index 337add2702..6e05c5dd22 100644
--- a/cpukit/libcsupport/src/getcwd.c
+++ b/cpukit/libcsupport/src/getcwd.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Get Current Working Directory
+ * @ingroup libcsupport
+ */
+
 /*
  * Copyright (c) 1989, 1991 The Regents of the University of California.
  * All rights reserved.
diff --git a/cpukit/libcsupport/src/ioctl.c b/cpukit/libcsupport/src/ioctl.c
index 4a6a2ef66f..b583722d59 100644
--- a/cpukit/libcsupport/src/ioctl.c
+++ b/cpukit/libcsupport/src/ioctl.c
@@ -1,6 +1,11 @@
-/*
- *  ioctl() system call
+/**
+ * @file
  *
+ * @brief ioctl() system call
+ * @ingroup libcsupport
+ */
+
+/*
  *  This routine is not defined in the POSIX 1003.1b standard but is
  *  commonly supported on most UNIX and POSIX systems.
  *
diff --git a/cpukit/libcsupport/src/kill_noposix.c b/cpukit/libcsupport/src/kill_noposix.c
index 62270e3499..9d1e1acf82 100644
--- a/cpukit/libcsupport/src/kill_noposix.c
+++ b/cpukit/libcsupport/src/kill_noposix.c
@@ -1,4 +1,9 @@
-/*
+/**
+ * @file
+ *
+ * @brief Kill No POSIX
+ * @ingroup libcsupport
+ *
  *  Marginal implementations of some POSIX API routines
  *  to be used when POSIX is disabled.
  *
@@ -6,7 +11,9 @@
  *    + _kill_r
  *    + __kill
  *    + sleep
- *
+ */
+
+/*
  *  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.
diff --git a/cpukit/libcsupport/src/posix_memalign.c b/cpukit/libcsupport/src/posix_memalign.c
index d67c0caf57..961cff05d7 100644
--- a/cpukit/libcsupport/src/posix_memalign.c
+++ b/cpukit/libcsupport/src/posix_memalign.c
@@ -1,6 +1,11 @@
-/*
- *  posix_memalign()
+/**
+ * @file
  *
+ * @brief Update call statistics
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/setegid.c b/cpukit/libcsupport/src/setegid.c
index d2084595b9..d19ced41f9 100644
--- a/cpukit/libcsupport/src/setegid.c
+++ b/cpukit/libcsupport/src/setegid.c
@@ -1,3 +1,19 @@
+/**
+ * @file
+ *
+ * @brief Get Real User, Effective User, Ral Group, and Effective Group IDs
+ * @ingroup libcsupport
+ */
+
+/*
+ *  COPYRIGHT (c) 1989-2007.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  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
diff --git a/cpukit/libcsupport/src/sup_fs_deviceerrno.c b/cpukit/libcsupport/src/sup_fs_deviceerrno.c
index 4316496561..b03b32329a 100644
--- a/cpukit/libcsupport/src/sup_fs_deviceerrno.c
+++ b/cpukit/libcsupport/src/sup_fs_deviceerrno.c
@@ -1,9 +1,14 @@
-/*
- *  IMFS Device Node Handlers
+/**
+ * @file
  *
- *  This file contains the set of handlers used to map operations on
- *  IMFS device nodes onto calls to the RTEMS Classic API IO Manager.
+ * @brief IMFS Device Node Handlers
+ * @ingroup Device IO Handler
  *
+ * 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-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/sup_fs_mount_iterate.c b/cpukit/libcsupport/src/sup_fs_mount_iterate.c
index 88cfca828c..67f143c5a9 100644
--- a/cpukit/libcsupport/src/sup_fs_mount_iterate.c
+++ b/cpukit/libcsupport/src/sup_fs_mount_iterate.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Mount table entry visitor.
+ * @ingroup Termios Termios
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/utsname.c b/cpukit/libcsupport/src/utsname.c
index cc9648510d..5af5e1a97d 100644
--- a/cpukit/libcsupport/src/utsname.c
+++ b/cpukit/libcsupport/src/utsname.c
@@ -1,3 +1,19 @@
+/**
+ * @file
+ *
+ * @brief Get System Name
+ * @ingroup utsname Service
+ */
+
+/*
+ *  COPYRIGHT (c) 1989-1999.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  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
diff --git a/cpukit/libcsupport/src/write_r.c b/cpukit/libcsupport/src/write_r.c
index 9f63b88222..c5e41b3711 100644
--- a/cpukit/libcsupport/src/write_r.c
+++ b/cpukit/libcsupport/src/write_r.c
@@ -1,6 +1,11 @@
-/*
- *  write_r() - POSIX 1003.1b 6.4.2 - Write to a File
+/**
+ * @file
  *
+ * @brief POSIX 1003.1b 6.4.2 - Write to a File
+ * @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *