libcsupport: Doxygen Enhancement Task #8

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

cpukit/libcsupport/include/rtems/assoc.h

@@ -85,6 +85,9 @@ const char *rtems_assoc_name_by_local(
   uint32_t
 );
 
+/**
+ *  @brief RTEMS Associate Name by Remote
+ */
 const char *rtems_assoc_name_by_remote(
   const rtems_assoc_t *,
   uint32_t

cpukit/libcsupport/include/rtems/libcsupport.h

@@ -56,6 +56,12 @@ Heap_Control *malloc_get_heap_pointer( void );
 extern void libc_init(void);
 extern int  host_errno(void);
 extern void fix_syscall_errno(void);
+
+/**
+ *  @brief RTEMS Malloc Get Free Information
+ * 
+ *  Find amount of free heap remaining
+ */
 extern size_t malloc_free_space(void);
 extern void open_dev_console(void);
 

cpukit/libcsupport/include/rtems/libio.h

@@ -4,6 +4,10 @@
  * @ingroup LibIO
  *
  * @brief Basic IO API.
+ * 
+ * This file contains the support infrastructure used to manage the
+ * table of integer style file descriptors used by the low level
+ * POSIX system calls like open(), read, fstat(), etc.
  */
 
 /*
@@ -1251,6 +1255,11 @@ typedef struct {
 
 /** @} */
 
+/**
+ * @brief RTEMS LibIO Initialization
+ * 
+ * Called by BSP startup code to initialize the libio subsystem.
+ */
 void rtems_libio_init(void);
 
 /**

cpukit/libcsupport/include/rtems/libio_.h

@@ -276,12 +276,26 @@ static inline void rtems_filesystem_instance_unlock(
  *  File Descriptor Routine Prototypes
  */
 
+/**
+ *  This routine searches the IOP Table for an unused entry.  If it
+ *  finds one, it returns it.  Otherwise, it returns NULL.
+ */
 rtems_libio_t *rtems_libio_allocate(void);
 
+/**
+ *  Convert UNIX fnctl(2) flags to ones that RTEMS drivers understand
+ */
 uint32_t rtems_libio_fcntl_flags( int fcntl_flags );
 
+/**
+ *  Convert RTEMS internal flags to UNIX fnctl(2) flags
+ */
 int rtems_libio_to_fcntl_flags( uint32_t flags );
 
+/**
+ *  This routine frees the resources associated with an IOP (file descriptor)
+ *  and clears the slot in the IOP Table.
+ */
 void rtems_libio_free(
   rtems_libio_t *iop
 );

cpukit/libcsupport/include/rtems/malloc.h

@@ -110,7 +110,7 @@ typedef void (*rtems_malloc_dirtier_t)(void *, size_t);
 extern rtems_malloc_dirtier_t rtems_malloc_dirty_helper;
 
 /**
- *  @brief Dirty memory function
+ *  @brief Dirty Memory Function
  *
  *  This method fills the specified area with a non-zero pattern
  *  to aid in debugging programs which do not initialize their

cpukit/libcsupport/src/__gettod.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  gettimeofday() - SVR4 and BSD4.3 extension required by Newlib
+ *  @file
  *
+ *  @brief Get the Date and Time
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -22,8 +27,11 @@
 #include <rtems/seterr.h>
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE_GETTIMEOFDAY)
-/*
+
- *  NOTE:  The solaris gettimeofday does not have a second parameter.
+/** 
+ *  SVR4 and BSD4.3 extension required by Newlib
+ * 
+ *  @note The solaris gettimeofday does not have a second parameter.
  */
 int gettimeofday(
   struct timeval  *tp,
@@ -54,7 +62,7 @@ int gettimeofday(
 
 #include <sys/reent.h>
 
-/*
+/**
  *  "Reentrant" version
  */
 int _gettimeofday_r(
@@ -68,10 +76,10 @@ int _gettimeofday_r(
 #endif
 
 #if defined(RTEMS_NEWLIB) && !defined(HAVE__GETTIMEOFDAY)
-/*
+
+/**
  *  "System call" version
  */
-
 int _gettimeofday(
   struct timeval  *tp,
   struct timezone *tzp

cpukit/libcsupport/src/__times.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  times() - POSIX 1003.1b 4.5.2 - Get Process Times
+ *  @file
  *
+ *  @brief Get Process Times
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,6 +29,9 @@
   #include <rtems/score/timestamp.h>
 #endif
 
+/**
+ *  POSIX 1003.1b 4.5.2 - Get Process Times
+ */
 clock_t _times(
    struct tms  *ptms
 )
@@ -79,12 +87,9 @@ clock_t _times(
   return ticks;
 } 
 
-/*
+/**
- *  times()
- *
  *  times() system call wrapper for _times() above.
  */
-
 clock_t times(
    struct tms  *ptms
 )
@@ -92,16 +97,13 @@ clock_t times(
   return _times( ptms );
 }
 
-/*
- *  _times_r
- *
- *  This is the Newlib dependent reentrant version of times().
- */
-
 #if defined(RTEMS_NEWLIB)
 
 #include <reent.h>
 
+/**
+ *  This is the Newlib dependent reentrant version of times().
+ */
 clock_t _times_r(
    struct _reent *ptr __attribute__((unused)),
    struct tms  *ptms

cpukit/libcsupport/src/assocnamebyremote.c

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

cpukit/libcsupport/src/cfgetispeed.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  cfgetispeed() - 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).
  *

cpukit/libcsupport/src/freenode.c

@@ -1,6 +1,10 @@
-/*
+/**
- *  freenode()
+ *  @file
  *
+ *  @brief Releases all Resources of a Location
+ *  @ingroup LibIOInternal
+ */
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libcsupport/src/getchark.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get Character from Stdin
+ *  @ingroup libcsupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).

cpukit/libcsupport/src/getlogin.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get User Name
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -15,10 +22,10 @@
 #include <unistd.h>
 #include <pwd.h>
 
-/*
+/**
  *  4.2.4 Get User Name, P1003.1b-1993, p. 87
  *
- *  NOTE:  P1003.1c/D10, p. 49 adds getlogin_r().
+ *  @note P1003.1c/D10, p. 49 adds getlogin_r().
  */
 char *getlogin( void )
 {
@@ -26,10 +33,10 @@ char *getlogin( void )
   return _POSIX_types_Getlogin_buffer;
 }
 
-/*
+/**
  *  4.2.4 Get User Name, P1003.1b-1993, p. 87
  *
- *  NOTE:  P1003.1c/D10, p. 49 adds getlogin_r().
+ *  @note P1003.1c/D10, p. 49 adds getlogin_r().
  */
 int getlogin_r(
   char   *name,

cpukit/libcsupport/src/libio.c

@@ -1,8 +1,11 @@
-/*
+/**
- *  This file contains the support infrastructure used to manage the
+ *  @file
- *  table of integer style file descriptors used by the low level
- *  POSIX system calls like open(), read, fstat(), etc.
  *
+ *  @brief File Descriptor Routines
+ *  @ingroup LibIOInternal
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -39,12 +42,6 @@
  */
 #undef ACCEPT_O_NDELAY_ALIAS
 
-/*
- *  rtems_libio_fcntl_flags
- *
- *  Convert UNIX fnctl(2) flags to ones that RTEMS drivers understand
- */
-
 static const rtems_assoc_t access_modes_assoc[] = {
   { "READ",       LIBIO_FLAGS_READ,  O_RDONLY },
   { "WRITE",      LIBIO_FLAGS_WRITE, O_WRONLY },
@@ -87,12 +84,6 @@ uint32_t rtems_libio_fcntl_flags( int fcntl_flags )
   return flags;
 }
 
-/*
- *  rtems_libio_to_fcntl_flags
- *
- *  Convert RTEMS internal flags to UNIX fnctl(2) flags
- */
-
 int rtems_libio_to_fcntl_flags( uint32_t flags )
 {
   int fcntl_flags = 0;
@@ -120,13 +111,6 @@ int rtems_libio_to_fcntl_flags( uint32_t flags )
   return fcntl_flags;
 }
 
-/*
- *  rtems_libio_allocate
- *
- *  This routine searches the IOP Table for an unused entry.  If it
- *  finds one, it returns it.  Otherwise, it returns NULL.
- */
-
 rtems_libio_t *rtems_libio_allocate( void )
 {
   rtems_libio_t *iop = NULL;
@@ -145,13 +129,6 @@ rtems_libio_t *rtems_libio_allocate( void )
   return iop;
 }
 
-/*
- *  rtems_libio_free
- *
- *  This routine frees the resources associated with an IOP (file descriptor)
- *  and clears the slot in the IOP Table.
- */
-
 void rtems_libio_free(
   rtems_libio_t *iop
 )

cpukit/libcsupport/src/libio_init.c

@@ -1,8 +1,11 @@
-/*
+/**
- *  This file contains the support infrastructure used to manage the
+ *  @file
- *  table of integer style file descriptors used by the low level
- *  POSIX system calls like open(), read, fstat(), etc.
  *
+ *  @brief RTEMS LibIO Initialization
+ *  @ingroup LibIO
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -38,12 +41,6 @@ rtems_id           rtems_libio_semaphore;
 rtems_libio_t     *rtems_libio_iops;
 rtems_libio_t     *rtems_libio_iop_freelist;
 
-/*
- *  rtems_libio_init
- *
- *  Called by BSP startup code to initialize the libio subsystem.
- */
-
 void rtems_libio_init( void )
 {
     rtems_status_code rc;

cpukit/libcsupport/src/malloc_dirtier.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  RTEMS Malloc Family -- Dirty Memory from Malloc
+ *  @file
  *
+ *  @brief Dirty Memory Function
+ *  @ingroup MallocSupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libcsupport/src/malloc_get_statistics.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  malloc_get_statistics Implementation
+ *  @file
  *
+ *  @brief Print Malloc Statistic Usage Report
+ *  @ingroup MallocSupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libcsupport/src/mallocfreespace.c

@@ -1,7 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS Malloc Get Free Information
+ *  @ingroup libcsupport
+ */
+
 /*
- *  RTEMS Malloc Get Free Information
- *
- *
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/libcsupport/src/readv.c

@@ -1,10 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief Read a Vector
+ *  @ingroup libcsupport
+ */
+
 /*
- *  readv() - POSIX 1003.1 - Read a Vector
- *
- *  OpenGroup URL:
- *
- *  http://www.opengroup.org/onlinepubs/009695399/functions/readv.html
- *
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,6 +24,13 @@
 #include <rtems/libio_.h>
 #include <rtems/seterr.h>
 
+/**
+ *  readv() - POSIX 1003.1 - Read a Vector
+ *
+ *  OpenGroup URL:
+ *
+ *  http://www.opengroup.org/onlinepubs/009695399/functions/readv.html
+ */
 ssize_t readv(
   int                 fd,
   const struct iovec *iov,

cpukit/libcsupport/src/setsid.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Create Session and Set Process Group ID
+ *  @ingroup libcsupport
+ */
+
 #if HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -6,10 +13,9 @@
 
 #include <rtems/seterr.h>
 
-/*
+/**
  *  4.3.2 Create Session and Set Process Group ID, P1003.1b-1993, p. 88
  */
-
 pid_t setsid( void )
 {
   rtems_set_errno_and_return_minus_one( EPERM );

cpukit/libcsupport/src/stat.c

@@ -1,8 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief Get File Status
+ *  @ingroup libcsupport
+ */
+
 /*
- *  stat() - POSIX 1003.1b 5.6.2 - Get File Status
- *
- *  Reused from lstat().
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -31,6 +34,11 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.6.2 - Get File Status
+ * 
+ *  Reused from lstat().
+ */
 int _STAT_NAME( const char *path, struct stat *buf )
 {
   int rv = 0;
@@ -48,16 +56,13 @@ int _STAT_NAME( const char *path, struct stat *buf )
   return rv;
 }
 
-/*
- *  _stat_r, _lstat_r
- *
- *  This is the Newlib dependent reentrant version of stat() and lstat().
- */
-
 #if defined(RTEMS_NEWLIB)
 
 #include <reent.h>
 
+/**
+ *  This is the Newlib dependent reentrant version of stat() and lstat().
+ */
 int _STAT_R_NAME(
   struct _reent *ptr __attribute__((unused)),
   const char    *path,

cpukit/libcsupport/src/sup_fs_check_permissions.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS File System Permissions Check Support
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *

cpukit/libcsupport/src/sup_fs_location.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief RTEMS File System Location Support
+ *  @ingroup LibIOInternal
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *

cpukit/libcsupport/src/termios_setinitialbaud.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Sets the Initial Baud in the Termios Context
+ *  @ingroup TermiostypesSupport
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).

cpukit/libcsupport/src/ttyname.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Demetermine Terminal Device Name
+ *  @ingroup libcsupport
+ */
+
 /*
  * Copyright (c) 1988, 1993
  *	The Regents of the University of California.  All rights reserved.
@@ -54,7 +61,7 @@
 
 static char ttyname_buf[sizeof (_PATH_DEV) + MAXNAMLEN];
 
-/*
+/**
  *  ttyname_r() - POSIX 1003.1b 4.7.2 - Demetermine Terminal Device Name
  */
 int ttyname_r(
@@ -99,10 +106,9 @@ int ttyname_r(
   return 0;
 }
 
-/*
+/**
  *  ttyname() - POSIX 1003.1b 4.7.2 - Determine Terminal Device Name
  */
-
 char *ttyname(
   int fd
 )

cpukit/libcsupport/src/utime.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  utime() - POSIX 1003.1b 5.5.6 - Set File Access and Modification Times
+ *  @file
  *
+ *  @brief Set File Access and Modification Times
+ *  @ingroup libcsupport
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,6 +25,9 @@
 
 #include <rtems/libio_.h>
 
+/**
+ *  POSIX 1003.1b 5.5.6 - Set File Access and Modification Times
+ */
 int utime( const char *path, const struct utimbuf *times )
 {
   int rv = 0;