libcsupport: GCI Doxygen Task #7

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

cpukit/libcsupport/include/rtems/assoc.h

@@ -101,6 +101,9 @@ char *rtems_assoc_name_by_local_bitfield(
   char *
 );
 
+/**
+ *  @brief RTEMS Associate Name by Remote Bitfield
+ */
 char *rtems_assoc_name_by_remote_bitfield(
   const rtems_assoc_t *,
   uint32_t  ,

cpukit/libcsupport/include/rtems/libcsupport.h

@@ -39,6 +39,12 @@ extern void malloc_dump(void);
  *  @brief Malloc Walk
  */
 extern bool malloc_walk(int source, bool printf_enabled);
+
+/**
+ *  @brief RTEMS Malloc Set Heap Pointer
+ * 
+ *  This routine is primarily used for debugging. 
+ */
 void malloc_set_heap_pointer(Heap_Control *new_heap);
 
 /**

cpukit/libcsupport/include/rtems/libio.h

@@ -1373,6 +1373,14 @@ static inline rtems_device_minor_number rtems_filesystem_dev_minor_t(
  *  Prototypes for filesystem
  */
 
+/**
+ *  @brief Base File System Initialization
+ *  
+ *  Initialize the foundation of the file system.  This is specified
+ *  by the structure rtems_filesystem_mount_table.  The usual
+ *  configuration is a single instantiation of the IMFS or miniIMFS with
+ *  a single "/dev" directory in it.
+ */
 void rtems_filesystem_initialize( void );
 
 typedef void (*rtems_libio_init_functions_t)(void);

cpukit/libcsupport/include/rtems/libio_.h

@@ -30,11 +30,11 @@ extern "C" {
 #endif
 
 /**
- * @defgroup LibIOInternal IO Internal Library
+ *  @defgroup LibIOInternal IO Internal Library
  *
- * @brief Internal IO library API and implementation.
+ *  @brief Internal IO library API and implementation.
  *
- * @{
+ *  @{
  */
 
 #define RTEMS_FILESYSTEM_SYMLOOP_MAX 32
@@ -62,7 +62,7 @@ extern const rtems_filesystem_file_handlers_r rtems_filesystem_null_handlers;
 extern rtems_filesystem_mount_table_entry_t rtems_filesystem_null_mt_entry;
 
 /**
- * @brief The global null location.
+ *  @brief The Global NULL Location
  *
  * Every operation and the open and fstat handlers of this location returns an
  * error status.  The errno is not touched by these operations and handlers.
@@ -770,10 +770,10 @@ void rtems_filesystem_eval_path_error(
 );
 
 /**
- * @brief Checks that the locations exist in the same file system instance.
+ *  @brief Checks that the Locations Exist in the Same File System Instance
  *
- * @retval 0 The locations exist and are in the same file system instance.
+ *  @retval 0 The locations exist and are in the same file system instance.
- * @retval -1 An error occured.  The @c errno indicates the error.
+ *  @retval -1 An error occured.  The @c errno indicates the error.
  */
 int rtems_filesystem_location_exists_in_same_instance_as(
   const rtems_filesystem_location_info_t *a,

cpukit/libcsupport/include/sys/termios.h

@@ -191,6 +191,11 @@ struct termios {
 #define	TCSAFLUSH	2
 
 int	tcdrain(int);
+
+/**
+ *  @brief Line Control Functions
+ *  POSIX 1003.1b 7.2.2 - Line Control Functions
+ */
 int	tcflow(int, int);
 int	tcflush(int, int);
 int	tcgetattr(int, struct termios *);
@@ -204,8 +209,16 @@ int	tcsendbreak(int, int);
  *  @brief Baud Rate Functions
  */
 speed_t	cfgetospeed(const struct termios *tp);
+
+/**
+ *  @brief Baud Rate Functions
+ */
 int	cfsetospeed(struct termios *tp, speed_t speed);
 speed_t	cfgetispeed(const struct termios *tp);
+
+/**
+ *  @brief Baud Rate Functions
+ */
 int	cfsetispeed(struct termios *tp, speed_t speed);
 
 #ifdef __cplusplus

cpukit/libcsupport/src/__usrenv.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS File System Location Support
+ *  @ingroup LibIOInternal
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).

cpukit/libcsupport/src/assocnamebyremotebitfield.c

@@ -1,6 +1,8 @@
-/*
+/**
- * assoc.c
+ *  @file
- *      rtems assoc routines
+ *
+ *  @brief RTEMS Associate Name by Remote Bitfield
+ *  @ingroup Associativity
  */
 
 #if HAVE_CONFIG_H

cpukit/libcsupport/src/base_fs.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  Base file system initialization
+ *  @file
  *
+ *  @brief Base File System Initialization
+ *  @ingroup LibIO
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,16 +29,6 @@
  *  Default mode for created files.
  */
 
-
-/*
- *  rtems_filesystem_initialize
- *
- *  Initialize the foundation of the file system.  This is specified
- *  by the structure rtems_filesystem_mount_table.  The usual
- *  configuration is a single instantiation of the IMFS or miniIMFS with
- *  a single "/dev" directory in it.
- */
-
 void rtems_filesystem_initialize( void )
 {
   int rv = 0;

cpukit/libcsupport/src/calloc.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  calloc()
+ *  @file
  *
+ *  @brief Allocate Space for Array in Memory
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libcsupport/src/cfsetispeed.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  cfsetispeed() - 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).
  *
@@ -24,6 +29,9 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
+/**
+ *  POSIX 1003.1b 7.1.3 - Baud Rate Functions
+ */
 int cfsetispeed(
   struct termios *tp,
   speed_t         speed

cpukit/libcsupport/src/cfsetospeed.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  cfsetospeed() - 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).
  *
@@ -24,6 +29,9 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
+/**
+ *  POSIX 1003.1b 7.1.3 - Baud Rate Functions
+ */
 int cfsetospeed(
   struct termios *tp,
   speed_t         speed

cpukit/libcsupport/src/fchmod.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  fchmod() - POSIX 1003.1b 5.6.4 - Change File Modes
+ *  @file
  *
+ *  @brief Change File Modes
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,6 +22,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.6.4 - Change File Modes
+ */
 int fchmod( int fd, mode_t mode )
 {
   int rv;

cpukit/libcsupport/src/getegid.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
@@ -9,11 +16,10 @@
 #include <rtems/seterr.h>
 #include <rtems/userenv.h>
 
-/*
+/**
  *  4.2.1 Get Real User, Effective User, Ral Group, and Effective Group IDs,
  *        P1003.1b-1993, p. 84
  */
-
 gid_t getegid( void )
 {
   return _POSIX_types_Egid;

cpukit/libcsupport/src/getuid.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get Real User, Effective User, Ral Group, and Effective Group IDs
+ *  @ingroup libcsupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
@@ -15,7 +22,7 @@
 
 #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/malloc.c

@@ -1,7 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS Malloc Family Implementation
+ *  @ingroup libcsupport
+ */
+
 /*
- *  RTEMS Malloc Family Implementation
- *
- *
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libcsupport/src/malloc_deferred.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Malloc Deferred Support
+ *  @ingroup libcsupport
+ */
+
 /*
  *  Process free requests deferred because they were from ISR
  *  or other critical section.

cpukit/libcsupport/src/mallocsetheapptr.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  RTEMS Malloc Set Heap Pointer -- Primarily for Debug
+ *  @file
  *
+ *  @brief RTEMS Malloc Set Heap Pointer
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libcsupport/src/mkfifo.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  mkfifo() - POSIX 1003.1b 5.4.1 - Make a FIFO Special File
+ *  @file
  *
+ *  @brief Make a FIFO Special File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,6 +22,9 @@
 #include <sys/stat.h>
 #include <errno.h>
 
+/**
+ *  POSIX 1003.1b 5.4.1 - Make a FIFO Special File
+ */
 int mkfifo(
   const  char *path,
   mode_t       mode

cpukit/libcsupport/src/open.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  open() - POSIX 1003.1 5.3.1 - Open a File
+ *  @file
  *
+ *  @brief Open a File
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -120,6 +125,9 @@ static int do_open(
   return rv;
 }
 
+/**
+*  POSIX 1003.1 5.3.1 - Open a File
+*/
 int open( const char *path, int oflag, ... )
 {
   int rv = 0;
@@ -144,16 +152,15 @@ int open( const char *path, int oflag, ... )
   return rv;
 }
 
-/*
+
- *  _open_r
- *
- *  This is the Newlib dependent reentrant version of open().
- */
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE__OPEN_R)
 
 #include <reent.h>
 
+/**
+ *  This is the Newlib dependent reentrant version of open().
+ */
 int _open_r(
   struct _reent *ptr __attribute__((unused)),
   const char    *buf,

cpukit/libcsupport/src/readdir_r.c

@@ -1,5 +1,8 @@
-/*
+/**
- *  readdir_r - reentrant version of readdir()
+ *  @file
+ *
+ *  @brief Read a Directory
+ *  @ingroup libcsupport
  */
 
 #if HAVE_CONFIG_H
@@ -13,10 +16,10 @@
 #include <errno.h>
 #include <stdio.h>
 
-/*
+/**
- * The RTEMS version of readdir is already thread-safe.
+ *  The RTEMS version of readdir is already thread-safe.
+ *  This routine is reentrant version of readdir().
  */
-
 int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result)
 {
      *result = readdir(dirp);

cpukit/libcsupport/src/setegid.c

@@ -25,7 +25,7 @@
 #include <rtems/seterr.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/strlcat.c

@@ -1,6 +1,11 @@
-/*
+/**
- * utils.c - various utility functions used in pppd.
+ *  @file
  *
+ *  @brief Concatenate a Strings
+ *  @ingroup libcsupport
+ */
+
+/*
  * Copyright (c) 1999 The Australian National University.
  * All rights reserved.
  *
@@ -24,9 +29,10 @@
 #include <string.h>
 
 #ifndef HAVE_STRLCAT
-/*
+
- * strlcat - like strcat/strncat, doesn't overflow destination buffer,
+/**
- * always leaves destination null-terminated (for len > 0).
+ *  like strcat/strncat, doesn't overflow destination buffer,
+ *  always leaves destination null-terminated (for len > 0).
  */
 size_t
 strlcat(

cpukit/libcsupport/src/sup_fs_exist_in_same_instance.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Checks that the Locations Exist in the Same File System Instance
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *

cpukit/libcsupport/src/tcflow.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  tcflow() - POSIX 1003.1b 7.2.2 - Line Control Functions
+ *  @file
  *
+ *  @brief Line Control Functions
+ *  @ingroup Termios
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libcsupport/src/umask.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  umask() - POSIX 1003.1b 5.3.3 - Set File Creation Mask
+ *  @file
  *
+ *  @brief Set File Creation Mask
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,6 +24,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.3.3 - Set File Creation Mask
+ */
 mode_t umask( mode_t cmask )
 {
   mode_t old_mask;