From cc390b62c4517e32447e2b2276ba77b0420c8e50 Mon Sep 17 00:00:00 2001
From: Alex Ivanov <alexivanov97@gmail.com>
Date: Tue, 11 Dec 2012 17:35:30 -0500
Subject: libcsupport: Doxygen enhancement GCI task #6

http://www.google-melange.com/gci/task/view/google/gci2012/7992212
---
 cpukit/libcsupport/include/rtems/assoc.h           | 15 +++++++++++----
 cpukit/libcsupport/include/sys/termios.h           |  4 ++++
 cpukit/libcsupport/src/__assert.c                  | 15 +++++++++++++--
 cpukit/libcsupport/src/assocnamebad.c              | 13 +++++--------
 cpukit/libcsupport/src/assocnamebylocal.c          |  8 +++++---
 cpukit/libcsupport/src/assocnamebylocalbitfield.c  |  8 +++++---
 cpukit/libcsupport/src/envlock.c                   |  7 +++++++
 cpukit/libcsupport/src/fchdir.c                    | 12 ++++++++++--
 cpukit/libcsupport/src/funlockfile.c               | 11 ++++++++++-
 cpukit/libcsupport/src/geteuid.c                   | 10 ++++++++--
 cpukit/libcsupport/src/getppid.c                   | 10 ++++++++--
 cpukit/libcsupport/src/isatty.c                    |  7 +++++++
 cpukit/libcsupport/src/malloc_report_statistics.c  |  9 +++++++--
 cpukit/libcsupport/src/malloc_statistics_helpers.c | 11 ++++++++---
 cpukit/libcsupport/src/putk.c                      | 11 ++++++++---
 cpukit/libcsupport/src/realloc.c                   |  9 +++++++--
 cpukit/libcsupport/src/rtems_putc.c                |  7 +++++++
 cpukit/libcsupport/src/symlink.c                   |  9 +++++++--
 cpukit/libcsupport/src/tcdrain.c                   | 12 ++++++++++--
 cpukit/libcsupport/src/tcsetpgrp.c                 | 12 ++++++++++--
 cpukit/libcsupport/src/unmount.c                   | 20 +++++++++++++-------
 cpukit/libcsupport/src/write.c                     | 20 ++++++++++++--------
 22 files changed, 182 insertions(+), 58 deletions(-)

diff --git a/cpukit/libcsupport/include/rtems/assoc.h b/cpukit/libcsupport/include/rtems/assoc.h
index 496ddb42cd..70ac56d662 100644
--- a/cpukit/libcsupport/include/rtems/assoc.h
+++ b/cpukit/libcsupport/include/rtems/assoc.h
@@ -77,6 +77,9 @@ uint32_t rtems_assoc_local_by_name(
   const char *
 );
 
+/**
+ *  @brief RTEMS Associate Name by Local
+ */
 const char *rtems_assoc_name_by_local(
   const rtems_assoc_t *,
   uint32_t
@@ -95,6 +98,9 @@ uint32_t rtems_assoc_remote_by_local_bitfield(
   uint32_t
 );
 
+/**
+ *  @brief RTEMS Associate Name by Local Bitfield
+ */
 char *rtems_assoc_name_by_local_bitfield(
   const rtems_assoc_t *,
   uint32_t  ,
@@ -128,11 +134,12 @@ const rtems_assoc_t *rtems_assoc_ptr_by_local(
 #define rtems_assoc_is_default(_ap) \
   ((_ap)->name && !strcmp((_ap)->name, RTEMS_ASSOC_DEFAULT_NAME))
 
-/*
- * what to return if a value is not found
- * this is not reentrant, but it really shouldn't be invoked anyway
+/**
+ *  @brief RTEMS Associate Bad Name
+ * 
+ *  what to return if a value is not found
+ *  this is not reentrant, but it really shouldn't be invoked anyway
  */
-
 const char *rtems_assoc_name_bad(
   uint32_t   bad_value
 );
diff --git a/cpukit/libcsupport/include/sys/termios.h b/cpukit/libcsupport/include/sys/termios.h
index f51cd3c0f3..dea74c4fe8 100644
--- a/cpukit/libcsupport/include/sys/termios.h
+++ b/cpukit/libcsupport/include/sys/termios.h
@@ -190,6 +190,10 @@ struct termios {
 #define	TCSADRAIN	1
 #define	TCSAFLUSH	2
 
+/**
+ *  @brief Line Control Functions
+ *  POSIX 1003.1b 7.2.2 - Line Control Functions
+ */
 int	tcdrain(int);
 
 /**
diff --git a/cpukit/libcsupport/src/__assert.c b/cpukit/libcsupport/src/__assert.c
index 07af01bc40..be0fa6c2e9 100644
--- a/cpukit/libcsupport/src/__assert.c
+++ b/cpukit/libcsupport/src/__assert.c
@@ -1,5 +1,11 @@
-/*  __assert - small RTEMS Specific Implementation
+/**
+ *  @file
  *
+ *  @brief Evaluate Assertion
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -16,7 +22,8 @@
 #include <rtems.h>
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE___ASSERT_FUNC)
-/*
+
+/**
  * Newlib 1.16.0 added this method.  Together these provide an
  * RTEMS safe, low memory implementation.
  */
@@ -39,6 +46,10 @@ void __assert_func(
 #endif
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE___ASSERT)
+
+/**
+ *  small RTEMS Specific Implementation
+ */
 void __assert(
   const char *file,
   int         line,
diff --git a/cpukit/libcsupport/src/assocnamebad.c b/cpukit/libcsupport/src/assocnamebad.c
index 375aabc35c..7977f88949 100644
--- a/cpukit/libcsupport/src/assocnamebad.c
+++ b/cpukit/libcsupport/src/assocnamebad.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Bad Name
+ *  @ingroup SET
  */
 
 #if HAVE_CONFIG_H
@@ -15,11 +17,6 @@
 #include <inttypes.h>
 #include <stdio.h>              /* sprintf */
 
-/*
- * what to return if a value is not found
- * this is not reentrant, but it really shouldn't be invoked anyway
- */
-
 const char *
 rtems_assoc_name_bad(
 #ifdef RTEMS_DEBUG
diff --git a/cpukit/libcsupport/src/assocnamebylocal.c b/cpukit/libcsupport/src/assocnamebylocal.c
index 16cf8de481..0dd47b86e8 100644
--- a/cpukit/libcsupport/src/assocnamebylocal.c
+++ b/cpukit/libcsupport/src/assocnamebylocal.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Name by Local
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H
diff --git a/cpukit/libcsupport/src/assocnamebylocalbitfield.c b/cpukit/libcsupport/src/assocnamebylocalbitfield.c
index b19364006c..d8895cbfd5 100644
--- a/cpukit/libcsupport/src/assocnamebylocalbitfield.c
+++ b/cpukit/libcsupport/src/assocnamebylocalbitfield.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Name by Local Bitfield
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H
diff --git a/cpukit/libcsupport/src/envlock.c b/cpukit/libcsupport/src/envlock.c
index cd24a6d467..bc6f02c9f7 100644
--- a/cpukit/libcsupport/src/envlock.c
+++ b/cpukit/libcsupport/src/envlock.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Global Environment Lock Support
+ *  @ingroup libcsupport
+ */
+
 /*
  *  Author: Till Straumann <strauman@slac.stanford.edu>, 3/2002
  */
diff --git a/cpukit/libcsupport/src/fchdir.c b/cpukit/libcsupport/src/fchdir.c
index 255e58fa5d..c5fec5ba9e 100644
--- a/cpukit/libcsupport/src/fchdir.c
+++ b/cpukit/libcsupport/src/fchdir.c
@@ -1,6 +1,11 @@
-/*
- *  fchdir() - compatible with SVr4, 4.4BSD and X/OPEN - Change Directory
+/**
+ *  @file
  *
+ *  @brief Change Directory
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,6 +25,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  compatible with SVr4, 4.4BSD and X/OPEN - Change Directory
+ */
 int fchdir( int fd )
 {
   int rv = 0;
diff --git a/cpukit/libcsupport/src/funlockfile.c b/cpukit/libcsupport/src/funlockfile.c
index 53362cf959..46e8af33bb 100644
--- a/cpukit/libcsupport/src/funlockfile.c
+++ b/cpukit/libcsupport/src/funlockfile.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Unlock File for Stdio
+ *  @ingroup libcsupport
+ */
+
 /*
  * Copyright (c) 2009 by
  * Ralf Corsépius, Ulm, Germany. All rights reserved.
@@ -14,7 +21,9 @@
 
 #include <stdio.h>
 
-/* This is a non-functional stub */
+/**
+ * This is a non-functional stub 
+ */
 void funlockfile(FILE* file __attribute__((unused)))
 {
 }
diff --git a/cpukit/libcsupport/src/geteuid.c b/cpukit/libcsupport/src/geteuid.c
index 753dabf997..bc4ee75601 100644
--- a/cpukit/libcsupport/src/geteuid.c
+++ b/cpukit/libcsupport/src/geteuid.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
@@ -15,11 +22,10 @@
 uid_t _POSIX_types_Euid = 0;
 */
 
-/*
+/**
  *  4.2.1 Get Real User, Effective User, Ral Group, and Effective Group IDs,
  *        P1003.1b-1993, p. 84
  */
-
 uid_t geteuid( void )
 {
   return _POSIX_types_Euid;
diff --git a/cpukit/libcsupport/src/getppid.c b/cpukit/libcsupport/src/getppid.c
index 0341356a1f..b0269d4aea 100644
--- a/cpukit/libcsupport/src/getppid.c
+++ b/cpukit/libcsupport/src/getppid.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get Process and Parent Process IDs
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -10,10 +17,9 @@
 
 pid_t _POSIX_types_Ppid = 0;
 
-/*
+/**
  *  4.1.1 Get Process and Parent Process IDs, P1003.1b-1993, p. 83
  */
-
 pid_t getppid( void )
 {
   return _POSIX_types_Ppid;
diff --git a/cpukit/libcsupport/src/isatty.c b/cpukit/libcsupport/src/isatty.c
index 1149f73437..54e2c69ae6 100644
--- a/cpukit/libcsupport/src/isatty.c
+++ b/cpukit/libcsupport/src/isatty.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Test whether a File Descriptor Refers to a Terminal 
+ *  @ingroup libcsupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/libcsupport/src/malloc_report_statistics.c b/cpukit/libcsupport/src/malloc_report_statistics.c
index 7af92d45d5..09c7b0f32f 100644
--- a/cpukit/libcsupport/src/malloc_report_statistics.c
+++ b/cpukit/libcsupport/src/malloc_report_statistics.c
@@ -1,6 +1,11 @@
-/*
- *  malloc_report_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/malloc_statistics_helpers.c b/cpukit/libcsupport/src/malloc_statistics_helpers.c
index 8de5320fbb..0e788c04f1 100644
--- a/cpukit/libcsupport/src/malloc_statistics_helpers.c
+++ b/cpukit/libcsupport/src/malloc_statistics_helpers.c
@@ -1,6 +1,11 @@
-/*
- *  _calloc_r Implementation
+/**
+ *  @file
  *
+ *  @brief Malloc Statistics Support
+ *  @ingroup MallocSupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -48,7 +53,7 @@ static void rtems_malloc_statistics_at_malloc(
       s->max_depth = current_depth;
 }
 
-/*
+/**
  *  If the pointer is not in the heap, then we won't be able to get its
  *  size and thus we skip updating the statistics.
  */
diff --git a/cpukit/libcsupport/src/putk.c b/cpukit/libcsupport/src/putk.c
index 53265ffbb5..f3d7758f67 100644
--- a/cpukit/libcsupport/src/putk.c
+++ b/cpukit/libcsupport/src/putk.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Write Character to Stream 
+ *  @ingroup libcsupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -13,9 +20,7 @@
 
 #include <rtems/bspIo.h>
 
-/*
- * putk
- *
+/**
  * Kernel putk (e.g. puts) function requiring minimal infrastrure.
  */
 void putk(const char *s)
diff --git a/cpukit/libcsupport/src/realloc.c b/cpukit/libcsupport/src/realloc.c
index d606f91f4d..eee6f79e69 100644
--- a/cpukit/libcsupport/src/realloc.c
+++ b/cpukit/libcsupport/src/realloc.c
@@ -1,6 +1,11 @@
-/*
- *  calloc()
+/**
+ *  @file
  *
+ *  @brief Reallocate Memory Block
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/rtems_putc.c b/cpukit/libcsupport/src/rtems_putc.c
index 8a2b022192..caf4294c9a 100644
--- a/cpukit/libcsupport/src/rtems_putc.c
+++ b/cpukit/libcsupport/src/rtems_putc.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS Output a Character
+ *  @ingroup libcsupport
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/symlink.c b/cpukit/libcsupport/src/symlink.c
index 07ab87fc57..3c0fd7b41a 100644
--- a/cpukit/libcsupport/src/symlink.c
+++ b/cpukit/libcsupport/src/symlink.c
@@ -1,6 +1,11 @@
-/*
- *  symlink() - POSIX 1003.1b - X.X.X - XXX
+/**
+ *  @file
  *
+ *  @brief Make a Symbolic Link to a File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/tcdrain.c b/cpukit/libcsupport/src/tcdrain.c
index 6dcf824b18..9e9f9acef2 100644
--- a/cpukit/libcsupport/src/tcdrain.c
+++ b/cpukit/libcsupport/src/tcdrain.c
@@ -1,6 +1,11 @@
-/*
- *  tcdrain() - POSIX 1003.1b 7.2.2 - Line Control Functions
+/**
+ *  @file
  *
+ *  @brief Line Control Functions
+ *  @ingroup Termios
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,6 +29,9 @@
 
 #include <rtems/libio.h>
 
+/**
+ *  POSIX 1003.1b 7.2.2 - Line Control Functions
+ */
 int tcdrain(
   int fd
 )
diff --git a/cpukit/libcsupport/src/tcsetpgrp.c b/cpukit/libcsupport/src/tcsetpgrp.c
index 1f547c5229..5b0d1f989e 100644
--- a/cpukit/libcsupport/src/tcsetpgrp.c
+++ b/cpukit/libcsupport/src/tcsetpgrp.c
@@ -1,6 +1,11 @@
-/*
- *  tcsetprgrp() - POSIX 1003.1b 7.2.4 - Set Foreground Process Group ID
+/**
+ *  @file
  *
+ *  @brief Set Foreground Process Group ID
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,6 +29,9 @@
 
 #include <rtems/libio.h>
 
+/**
+ *  POSIX 1003.1b 7.2.4 - Set Foreground Process Group ID
+ */
 int tcsetpgrp(
   int fd __attribute__((unused)),
   pid_t pid __attribute__((unused)) )
diff --git a/cpukit/libcsupport/src/unmount.c b/cpukit/libcsupport/src/unmount.c
index a6e0f40442..06141b599a 100644
--- a/cpukit/libcsupport/src/unmount.c
+++ b/cpukit/libcsupport/src/unmount.c
@@ -1,11 +1,11 @@
-/*
- *  unmount() - Unmount a File System
- *
- *  This routine is not defined in the POSIX 1003.1b standard but
- *  in some form is supported on most UNIX and POSIX systems.  This
- *  routine is necessary to mount instantiations of a file system
- *  into the file system name space.
+/**
+ *  @file
  *
+ *  @brief Unmount a File System
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -34,6 +34,12 @@ static bool contains_root_or_current_directory(
   return mt_entry == root->mt_entry || mt_entry == current->mt_entry;
 }
 
+/**
+ *  This routine is not defined in the POSIX 1003.1b standard but
+ *  in some form is supported on most UNIX and POSIX systems.  This
+ *  routine is necessary to mount instantiations of a file system
+ *  into the file system name space.
+ */
 int unmount( const char *path )
 {
   int rv = 0;
diff --git a/cpukit/libcsupport/src/write.c b/cpukit/libcsupport/src/write.c
index dc1255867d..e96e938b0b 100644
--- a/cpukit/libcsupport/src/write.c
+++ b/cpukit/libcsupport/src/write.c
@@ -1,6 +1,11 @@
-/*
- *  write() - POSIX 1003.1b 6.4.2 - Write to a File
+/**
+ *  @file
  *
+ *  @brief Write to a File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -16,13 +21,12 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
-/*
- * write
- *
- * This routine writes count bytes from from buffer pointed to by buffer
- * to the file associated with the open file descriptor, fildes.
+/**
+ *  POSIX 1003.1b 6.4.2 - Write to a File
+ * 
+ *  This routine writes count bytes from from buffer pointed to by buffer
+ *  to the file associated with the open file descriptor, fildes.
  */
-
 ssize_t write(
   int         fd,
   const void *buffer,
-- 
cgit v1.2.3