libcsupport: Doxygen enhancement task #5

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

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

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

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

cpukit/libcsupport/include/rtems/malloc.h

@@ -26,6 +26,14 @@
 extern "C" {
 #endif
 
+/**
+ *  @defgroup MallocSupport Malloc Support
+ *
+ *  @ingroup libcsupport
+ *
+ *  @brief RTEMS extensions to the Malloc Family
+ */
+
 /**
  *  @brief C program heap control.
  *
@@ -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

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

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

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

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

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,

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

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

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
 )

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
 )

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

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

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

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

cpukit/libcsupport/src/mallocinfo.c

@@ -1,7 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS Malloc Get Status Information
+ *  @ingroup libcsupport
+ */
+
 /*
- *  RTEMS Malloc Get Status Information
- *
- *
  *  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
 )

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

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

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

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

cpukit/libcsupport/src/sync.c

@@ -1,12 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief Synchronize Data on Disk with Memory 
+ *  @ingroup libcsupport
+ */
+
 /*
- *  sync() - XXX ??? where is this defined
- *
- *  This function operates by as follows:
- *    for all threads
- *      for all FILE *
- *         fsync()
- *         fdatasync()
- *
  *  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)
 {
 

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

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,