[PATCH] libcsupport: Clean up Doxygen Task #1

[Sebastian Huber]

On 08/12/12 15:08, Gedare Bloom wrote:
> From: Alex Ivanov <alexivanov97 at gmail.com>
>
> http://www.google-melange.com/gci/task/view/google/gci2012/7985214
> ---
>   cpukit/libcsupport/include/rtems/assoc.h           |   11 +++++++++++
>   cpukit/libcsupport/include/rtems/libio.h           |   13 +++++++++----
>   cpukit/libcsupport/include/rtems/malloc.h          |   11 +++++++++++
>   cpukit/libcsupport/include/sys/statvfs.h           |    8 ++++++++
>   cpukit/libcsupport/include/sys/termios.h           |   12 ++++++++++++
>   cpukit/libcsupport/src/_malloc_r.c                 |    8 ++++++--
>   .../libcsupport/src/assoclocalbyremotebitfield.c   |    8 +++++---
>   cpukit/libcsupport/src/assocremotebylocal.c        |    8 +++++---
>   cpukit/libcsupport/src/fstat.c                     |    9 +++++++--
>   cpukit/libcsupport/src/ftrylockfile.c              |   11 ++++++++++-
>   cpukit/libcsupport/src/getpgrp.c                   |   10 ++++++++--
>   cpukit/libcsupport/src/getrusage.c                 |    7 +++++++
>   cpukit/libcsupport/src/lchown.c                    |   14 +++++++++++---
>   cpukit/libcsupport/src/lseek.c                     |    9 +++++++--
>   .../src/malloc_report_statistics_plugin.c          |    9 +++++++--
>   cpukit/libcsupport/src/mount-mgr.c                 |   19 ++++++++++++++-----
>   cpukit/libcsupport/src/newlibc_exit.c              |   17 +++++++++++++----
>   cpukit/libcsupport/src/open_dev_console.c          |   12 +++++++-----
>   cpukit/libcsupport/src/rtems_heap_null_extend.c    |    7 +++++++
>   cpukit/libcsupport/src/setuid.c                    |   10 ++++++++--
>   cpukit/libcsupport/src/statvfs.c                   |    7 +++++++
>   cpukit/libcsupport/src/strlcpy.c                   |   12 +++++++++---
>   cpukit/libcsupport/src/tcflush.c                   |    7 +++++++
>   cpukit/libcsupport/src/termios.c                   |    9 +++++++--
>   cpukit/libcsupport/src/writev.c                    |    9 +++++++--
>   25 files changed, 210 insertions(+), 47 deletions(-)
>
> diff --git a/cpukit/libcsupport/include/rtems/assoc.h b/cpukit/libcsupport/include/rtems/assoc.h
> index f55d3fe..eb03cb6 100644
> --- a/cpukit/libcsupport/include/rtems/assoc.h
> +++ b/cpukit/libcsupport/include/rtems/assoc.h
> @@ -15,6 +15,14 @@
>   extern "C" {
>   #endif
>   
> +/**
> + * @defgroup AssocSupport RTEMS Associativity Support
> + *
> + * @ingroup libcsupport
> + *
> + * @brief RTEMS Associativity Routines
> + */
> +

Here we have a new group but no @{ ... @} ?

[...]
> diff --git a/cpukit/libcsupport/include/rtems/libio.h b/cpukit/libcsupport/include/rtems/libio.h
> index 9374f3a..ba2736f 100644
> --- a/cpukit/libcsupport/include/rtems/libio.h
> +++ b/cpukit/libcsupport/include/rtems/libio.h
> @@ -1146,7 +1146,7 @@ int rtems_filesystem_default_fcntl(
>   typedef off_t rtems_off64_t __attribute__((deprecated));
>   
>   /**
> - * @brief Gets the mount handler for the file system @a type.
> + * @brief Gets the Mount Handler for the File System
>    *
>    * @return The file system mount handler associated with the @a type, or
>    * @c NULL if no such association exists.
> @@ -1378,6 +1378,11 @@ void rtems_filesystem_initialize( void );
>   typedef void (*rtems_libio_init_functions_t)(void);
>   extern  rtems_libio_init_functions_t rtems_libio_init_helper;
>   
> +/**
> + *  @brief Open a Developer Console
> + *
> + *  This is a replaceable stub which opens the console, if present.
> + */
>   void    open_dev_console(void);
>   
>   typedef void (*rtems_libio_supp_functions_t)(void);
> @@ -1496,7 +1501,7 @@ extern const rtems_filesystem_table_t rtems_filesystem_table [];
>   extern rtems_chain_control rtems_filesystem_mount_table;
>   
>   /**
> - * @brief Registers a file system @a type.
> + * @brief Registers a File System
>    *
>    * The @a mount_h handler will be used to mount a file system of this @a type.
>    *
> @@ -1509,7 +1514,7 @@ int rtems_filesystem_register(
>   );
>   
>   /**
> - * @brief Unregisters a file system @a type.
> + * @brief Unregisters a File System
>    *
>    * @retval 0 Successful operation.
>    * @retval -1 An error occured.  The @c errno indicates the error.
> @@ -1616,7 +1621,7 @@ typedef bool (*rtems_per_filesystem_routine)(
>   );
>   
>   /**
> - * @brief Iterates over all file system types.
> + * @brief Iterates over all File System Types
>    *
>    * For each file system type the @a routine will be called with the entry and
>    * the @a routine_arg parameter.

I don't think that random capitalizations and removal of '.' at the end 
of a sentence are a documentation improvement.  It is all right to add 
something in case of non-existing Doxygen comments, but changing 
existing Doxygen comments should be done more careful.

[...]

-- 
Sebastian Huber, embedded brains GmbH

Address : Obere Lagerstr. 30, D-82178 Puchheim, Germany
Phone   : +49 89 18 90 80 79-6
Fax     : +49 89 18 90 80 79-9
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.