[PATCH] libcsupport: Clean up Doxygen Task #1

[Joel Sherrill]

Sorry for not doing this inline but that's what my tablet client does.

@brief text really should be in what is called Title Case in the States. They are used like table of content entries and should not have periods.

The missing marker is a mistake in the instructions and something no one thought about.

Sebastian Huber <sebastian.huber at embedded-brains.de> wrote:


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.

_______________________________________________
rtems-devel mailing list
rtems-devel at rtems.org
http://www.rtems.org/mailman/listinfo/rtems-devel