libcsupport: Doxygen enhancement GCI task #6

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

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
 );

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);
 
 /**

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,

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

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

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

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
  */

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;

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)))
 {
 }

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;

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;

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).

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).
  *

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.
  */

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)

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).
  *

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.
  *

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).
  *

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
 )

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)) )

cpukit/libcsupport/src/unmount.c

@@ -1,11 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief Unmount a File System
+ *  @ingroup libcsupport
+ */
+
 /*
- *  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.
- *
  *  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;

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,