libcsupport: Doxygen enhancement task #5

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

25 files changed, 203 insertions, 54 deletions

diff --git a/cpukit/libcsupport/include/rtems/assoc.h b/cpukit/libcsupport/include/rtems/assoc.h
index 2401661e1f..48234c9fb4 100644
--- a/cpukit/libcsupport/include/rtems/assoc.h
+++ b/cpukit/libcsupport/include/rtems/assoc.h
@@ -40,6 +40,9 @@ const rtems_assoc_t *rtems_assoc_ptr_by_name(
   const char *
 );
 
+/**
+ *  @brief RTEMS Associate Pointer by Remote
+ */
 const rtems_assoc_t *rtems_assoc_ptr_by_remote(
   const rtems_assoc_t *,
   uint32_t
@@ -50,6 +53,9 @@ uint32_t rtems_assoc_remote_by_local(
   uint32_t
 );
 
+/**
+ *  @brief RTEMS Associate Local by Remote
+ */
 uint32_t rtems_assoc_local_by_remote(
   const rtems_assoc_t *,
   uint32_t
diff --git a/cpukit/libcsupport/include/rtems/libcsupport.h b/cpukit/libcsupport/include/rtems/libcsupport.h
index a3e5517046..600ee84562 100644
--- a/cpukit/libcsupport/include/rtems/libcsupport.h
+++ b/cpukit/libcsupport/include/rtems/libcsupport.h
@@ -40,6 +40,12 @@ extern void malloc_dump(void);
  */
 extern bool malloc_walk(int source, bool printf_enabled);
 void malloc_set_heap_pointer(Heap_Control *new_heap);
+
+/**
+ *  @brief RTEMS Malloc Get Heap Pointer
+ * 
+ *  This routine is primarily used for debugging. 
+ */
 Heap_Control *malloc_get_heap_pointer( void );
 extern void libc_init(void);
 extern int  host_errno(void);
@@ -47,6 +53,11 @@ extern void fix_syscall_errno(void);
 extern size_t malloc_free_space(void);
 extern void open_dev_console(void);
 
+/**
+ *  @brief RTEMS Malloc Get Status Information
+ * 
+ *  Find amount of free heap remaining.
+ */
 extern int malloc_info(Heap_Information_block *the_info);
 
 /*
diff --git a/cpukit/libcsupport/include/rtems/libio_.h b/cpukit/libcsupport/include/rtems/libio_.h
index 91035b1757..2ab40eef2a 100644
--- a/cpukit/libcsupport/include/rtems/libio_.h
+++ b/cpukit/libcsupport/include/rtems/libio_.h
@@ -680,6 +680,9 @@ static inline void rtems_filesystem_eval_path_put_back_token(
   ctx->tokenlen = 0;
 }
 
+/**
+ *  @brief RTEMS File System Eval Eat Delimiter Path
+ */
 void rtems_filesystem_eval_path_eat_delimiter(
   rtems_filesystem_eval_path_context_t *ctx
 );
diff --git a/cpukit/libcsupport/include/rtems/malloc.h b/cpukit/libcsupport/include/rtems/malloc.h
index 9d475d33b1..6b0dfa0e65 100644
--- a/cpukit/libcsupport/include/rtems/malloc.h
+++ b/cpukit/libcsupport/include/rtems/malloc.h
@@ -27,6 +27,14 @@ extern "C" {
 #endif
 
 /**
+ *  @defgroup MallocSupport Malloc Support
+ *
+ *  @ingroup libcsupport
+ *
+ *  @brief RTEMS extensions to the Malloc Family
+ */
+
+/**
  *  @brief C program heap control.
  *
  *  This is the pointer to the heap control structure used to manage the C
@@ -211,7 +219,7 @@ rtems_status_code rtems_heap_extend(
 );
 
 /**
- * @brief Greedy allocate that empties the heap.
+ *  @brief Greedy Allocate that Empties the Heap
  *
  * Afterward the heap has at most @a block_count allocatable blocks of sizes
  * specified by @a block_sizes.  The @a block_sizes must point to an array with
diff --git a/cpukit/libcsupport/include/sys/termios.h b/cpukit/libcsupport/include/sys/termios.h
index d763c896e8..dc4f9a1faf 100644
--- a/cpukit/libcsupport/include/sys/termios.h
+++ b/cpukit/libcsupport/include/sys/termios.h
@@ -22,6 +22,12 @@
 extern "C" {
 #endif
 
+/**
+ *  @ingroup Termios
+ *
+ *  @brief POSIX Termios Implementation
+ */
+
 typedef unsigned char	cc_t;
 typedef unsigned int	speed_t;
 typedef unsigned int	tcflag_t;
@@ -194,6 +200,9 @@ pid_t	tcgetprgrp(int);
 int	tcsetprgrp(int, pid_t);
 int	tcsendbreak(int, int);
 
+/**
+ *  @brief Baud Rate Functions
+ */
 speed_t	cfgetospeed(const struct termios *tp);
 int	cfsetospeed(struct termios *tp, speed_t speed);
 speed_t	cfgetispeed(const struct termios *tp);
diff --git a/cpukit/libcsupport/src/__getpid.c b/cpukit/libcsupport/src/__getpid.c
index 932a4f170a..96e1a3f813 100644
--- a/cpukit/libcsupport/src/__getpid.c
+++ b/cpukit/libcsupport/src/__getpid.c
@@ -1,6 +1,8 @@
-/*
- *  Some C Libraries reference this routine since they think getpid is
- *  a real system call.
+/**
+ *  @file
+ *
+ *  @brief Get Process Id
+ *  @ingroup libcsupport
  */
 
 #if HAVE_CONFIG_H
@@ -9,6 +11,10 @@
 
 #include <unistd.h>
 
+/**
+ *  Some C Libraries reference this routine since they think getpid is
+ *  a real system call.
+ */
 pid_t __getpid(void)
 {
   return getpid();
diff --git a/cpukit/libcsupport/src/_calloc_r.c b/cpukit/libcsupport/src/_calloc_r.c
index 391643cf63..c86d3604b3 100644
--- a/cpukit/libcsupport/src/_calloc_r.c
+++ b/cpukit/libcsupport/src/_calloc_r.c
@@ -1,6 +1,11 @@
-/*
- *  _calloc_r Implementation
+/**
+ *  @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/_free_r.c b/cpukit/libcsupport/src/_free_r.c
index 22f99ae260..411cb2b3ce 100644
--- a/cpukit/libcsupport/src/_free_r.c
+++ b/cpukit/libcsupport/src/_free_r.c
@@ -1,6 +1,11 @@
-/*
- *  _free_r Implementation
+/**
+ *  @file
  *
+ *  @brief Allocate and Free Dynamic Memory 
+ *  @ingroup libcsupport
+ */
+
+/* 
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/_rename_r.c b/cpukit/libcsupport/src/_rename_r.c
index c501472fc1..183717fc1d 100644
--- a/cpukit/libcsupport/src/_rename_r.c
+++ b/cpukit/libcsupport/src/_rename_r.c
@@ -1,6 +1,11 @@
-/*
- *  _rename_r() - POSIX 1003.1b - 5.3.4 - Rename a file
+/**
+ *  @file
  *
+ *  @brief Rename a File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -22,6 +27,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b - 5.3.4 - Rename a file
+ */
 int _rename_r(
   struct _reent *ptr __attribute__((unused)),
   const char    *old,
diff --git a/cpukit/libcsupport/src/assoclocalbyremote.c b/cpukit/libcsupport/src/assoclocalbyremote.c
index 6146fd32ca..24a86d82c7 100644
--- a/cpukit/libcsupport/src/assoclocalbyremote.c
+++ b/cpukit/libcsupport/src/assoclocalbyremote.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Local by Remote
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H
diff --git a/cpukit/libcsupport/src/assocptrbyremote.c b/cpukit/libcsupport/src/assocptrbyremote.c
index 1c929425a7..465158195b 100644
--- a/cpukit/libcsupport/src/assocptrbyremote.c
+++ b/cpukit/libcsupport/src/assocptrbyremote.c
@@ -1,6 +1,8 @@
-/*
- * assoc.c
- *      rtems assoc routines
+/**
+ *  @file
+ *
+ *  @brief RTEMS Associate Pointer by Remote
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H
diff --git a/cpukit/libcsupport/src/cfgetospeed.c b/cpukit/libcsupport/src/cfgetospeed.c
index 388c26e290..f1a4fc8dac 100644
--- a/cpukit/libcsupport/src/cfgetospeed.c
+++ b/cpukit/libcsupport/src/cfgetospeed.c
@@ -1,6 +1,11 @@
-/*
- *  cfgetospeed() - 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).
  *
@@ -21,6 +26,9 @@
 #include <errno.h>
 #include <termios.h>
 
+/**
+ *  POSIX 1003.1b 7.1.3 - Baud Rate Functions
+ */
 speed_t cfgetospeed(
   const struct termios *tp
 )
diff --git a/cpukit/libcsupport/src/ctermid.c b/cpukit/libcsupport/src/ctermid.c
index 5699dcee1f..8df70e1263 100644
--- a/cpukit/libcsupport/src/ctermid.c
+++ b/cpukit/libcsupport/src/ctermid.c
@@ -1,6 +1,11 @@
-/*
- *  ctermid() - POSIX 1003.1b 4.7.1 - Generate Terminal Pathname
+/**
+ *  @file
  *
+ *  @brief Generate Terminal Pathname
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,6 +26,9 @@
 
 static char *ctermid_name = "/dev/console";
 
+/**
+ *  ctermid() - POSIX 1003.1b 4.7.1 - Generate Terminal Pathname
+ */
 char *ctermid(
   char *s
 )
diff --git a/cpukit/libcsupport/src/ftruncate.c b/cpukit/libcsupport/src/ftruncate.c
index a6eb16fd0d..8ec852de38 100644
--- a/cpukit/libcsupport/src/ftruncate.c
+++ b/cpukit/libcsupport/src/ftruncate.c
@@ -1,6 +1,11 @@
-/*
- *  ftruncate() - Truncate a File to the Specified Length
+/**
+ *  @file
  *
+ *  @brief Truncate a File to the Specified Length
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/getgid.c b/cpukit/libcsupport/src/getgid.c
index 3e38dde0ef..cb8e7e97fc 100644
--- a/cpukit/libcsupport/src/getgid.c
+++ b/cpukit/libcsupport/src/getgid.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
@@ -5,7 +12,7 @@
 #include <unistd.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/getpagesize.c b/cpukit/libcsupport/src/getpagesize.c
index 2b93415f21..24776ec920 100644
--- a/cpukit/libcsupport/src/getpagesize.c
+++ b/cpukit/libcsupport/src/getpagesize.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get System Page Size
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -5,7 +12,7 @@
 #include <unistd.h>
 #include <sys/param.h>
 
-/*
+/**
  *  Get System Page Size (from SVR4 and 4.2+ BSD)
  *
  *  This is not a functional version but the SPARC backend for at least
diff --git a/cpukit/libcsupport/src/mallocgetheapptr.c b/cpukit/libcsupport/src/mallocgetheapptr.c
index a25426ae6e..7392d67831 100644
--- a/cpukit/libcsupport/src/mallocgetheapptr.c
+++ b/cpukit/libcsupport/src/mallocgetheapptr.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Malloc Get Heap Pointer -- Primarily for Debug
+/**
+ *  @file
  *
+ *  @brief RTEMS Malloc Get Heap Pointer
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/libcsupport/src/mallocinfo.c b/cpukit/libcsupport/src/mallocinfo.c
index 1532608420..63c349d762 100644
--- a/cpukit/libcsupport/src/mallocinfo.c
+++ b/cpukit/libcsupport/src/mallocinfo.c
@@ -1,7 +1,11 @@
-/*
- *  RTEMS Malloc Get Status Information
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Malloc Get Status Information
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,10 +21,6 @@
 #include <rtems/malloc.h>
 #include <rtems/score/protectedheap.h>
 
-/*
- *  Find amount of free heap remaining
- */
-
 int malloc_info(
   Heap_Information_block *the_info
 )
diff --git a/cpukit/libcsupport/src/newlibc_init.c b/cpukit/libcsupport/src/newlibc_init.c
index ff6d438b33..110f721554 100644
--- a/cpukit/libcsupport/src/newlibc_init.c
+++ b/cpukit/libcsupport/src/newlibc_init.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Newlib Initialization
+ *  @ingroup libcsupport
+ */
+
 /*
  *  Implementation of hooks for the CYGNUS newlib libc
  *  These hooks set things up so that:
@@ -17,7 +24,7 @@
 
 #if defined(RTEMS_NEWLIB)
 
-/*
+/**
  *  Init libc for CYGNUS newlib
  *
  *  Set up _REENT to use our global libc_global_reent.
@@ -29,8 +36,6 @@
  *  create, delete, switch, exit, etc.
  *
  */
-
-
 void
 libc_init(void)
 {
diff --git a/cpukit/libcsupport/src/pipe.c b/cpukit/libcsupport/src/pipe.c
index 97f2bd4b65..21d3205cf1 100644
--- a/cpukit/libcsupport/src/pipe.c
+++ b/cpukit/libcsupport/src/pipe.c
@@ -1,6 +1,11 @@
-/*
- *  pipe() - POSIX 1003.1b 6.1.1 Create an Inter-Process Channel
+/**
+ *  @file
  *
+ *  @brief Create an Inter-Process Channel
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,6 +25,9 @@
 #include <rtems/seterr.h>
 #include <rtems/pipe.h>
 
+/**
+ *  POSIX 1003.1b 6.1.1 Create an Inter-Process Channel
+ */
 int pipe(
   int filsdes[2]
 )
diff --git a/cpukit/libcsupport/src/rtems_heap_greedy.c b/cpukit/libcsupport/src/rtems_heap_greedy.c
index 7e5dc16e7e..a63ff913cd 100644
--- a/cpukit/libcsupport/src/rtems_heap_greedy.c
+++ b/cpukit/libcsupport/src/rtems_heap_greedy.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Greedy Allocate that Empties the Heap
+ *  @ingroup MallocSupport
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/sup_fs_next_token.c b/cpukit/libcsupport/src/sup_fs_next_token.c
index 451d81bbfe..2034774834 100644
--- a/cpukit/libcsupport/src/sup_fs_next_token.c
+++ b/cpukit/libcsupport/src/sup_fs_next_token.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS File System Eval Eat Delimiter Path
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libcsupport/src/sync.c b/cpukit/libcsupport/src/sync.c
index 7b17db15ef..2e8386754c 100644
--- a/cpukit/libcsupport/src/sync.c
+++ b/cpukit/libcsupport/src/sync.c
@@ -1,12 +1,11 @@
-/*
- *  sync() - XXX ??? where is this defined
- *
- *  This function operates by as follows:
- *    for all threads
- *      for all FILE *
- *         fsync()
- *         fdatasync()
+/**
+ *  @file
  *
+ *  @brief Synchronize Data on Disk with Memory 
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -79,6 +78,13 @@ static void sync_per_thread(Thread_Control *t)
  */
 extern struct _reent * const _global_impure_ptr __ATTRIBUTE_IMPURE_PTR__;
 
+/**
+ * This function operates by as follows:
+ *    for all threads
+ *      for all FILE *
+ *         fsync()
+ *         fdatasync()
+ */
 void sync(void)
 {
 
diff --git a/cpukit/libcsupport/src/utimes.c b/cpukit/libcsupport/src/utimes.c
index 648cb8b7a6..ef982d1c60 100644
--- a/cpukit/libcsupport/src/utimes.c
+++ b/cpukit/libcsupport/src/utimes.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Change File Last Access and Modification Times 
+ *  @ingroup libcsupport
+ */
+
 /*
  *  Written by: Vinu Rajashekhar <vinutheraj@gmail.com>
  *
diff --git a/cpukit/libcsupport/src/vprintk.c b/cpukit/libcsupport/src/vprintk.c
index 2524e88a3f..b1aceccbe9 100644
--- a/cpukit/libcsupport/src/vprintk.c
+++ b/cpukit/libcsupport/src/vprintk.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Print Formatted Output
+ *  @ingroup libcsupport
+ */
+
 /*
  * (C) Copyright 1997 -
  * - NavIST Group - Real-Time Distributed Systems and Industrial Automation
@@ -31,9 +38,7 @@ static void printNum(
   char lead
 );
 
-/*
- *  vprintk
- *
+/**
  *  A simplified version of printf intended for use when the
  *  console is not yet initialized or in ISR's.
  *
@@ -146,11 +151,10 @@ void vprintk(
   }
 }
 
-/*
- * printNum - print number in a given base.
- * Arguments
- *    num - number to print
- *    base - base used to print the number.
+/**
+ *  @brief Print Number in a Given Base
+ *  @param[in] num is the number to print
+ *  @param[in] base is the base used to print the number
  */
 static void printNum(
   long num,