[PATCH] rtems misc: Clean up Doxygen GCI Task #6

[Sebastian Huber]

On 12/05/2012 04:52 PM, Gedare Bloom wrote:
> diff --git a/cpukit/rtems/include/rtems/rtems/dpmem.h
> b/cpukit/rtems/include/rtems/rtems/dpmem.h
> index a4cf251..e305b31 100644
> --- a/cpukit/rtems/include/rtems/rtems/dpmem.h
> +++ b/cpukit/rtems/include/rtems/rtems/dpmem.h
> @@ -84,13 +84,24 @@ RTEMS_DPMEM_EXTERN Objects_Information
> _Dual_ported_memory_Information;
>   void _Dual_ported_memory_Manager_initialization(void);
>
>   /**
> - *  @brief rtems_port_create
> + *  @brief RTEMS Create Port

I would prefer to have a complete sentence as a brief description, e.g. "@brief 
Creates a port into a dual-ported memory area.".

>    *
>    *  This routine implements the rtems_port_create directive.

What is the use of such a sentence?

> The port
>    *  will have the name name.

This is duplicated with the parameter description.  If we really want to 
duplicate this, then Doxygen has the "@a" tag to mark argument names, e.g. "The 
port will have the name @a name."

> The port maps onto an area of dual ported
>    *  memory of length bytes which has internal_start and external_start
>    *  as the internal and external starting addresses, respectively.
>    *  It returns the id of the created port in ID.
> + *
> + *  @param[in] name is the user defined port name

I would prefer to have a complete sentence as a parameter description, e.g. 
"@param[in] name The port object name."

> + *  @param[in] internal_start is the internal start address of port
> + *  @param[in] external_start is the external start address of port
> + *  @param[in] length is the physical length in bytes
> + *  @param[in] id is the address of port id to set

The id is an output parameter, e.g. "@param[out]".

> + *
> + *  @return This method returns RTEMS_SUCCESSFUL if there was not an
> + *          error.  Otherwise, a status code is returned indicating the
> + *          source of the error.  If successful, the id will
> + *          be filled in with the port id.

I would prefer a listing of return status codes, e.g.

  *  @retval RTEMS_SUCCESSFUL Successful operation.
  *  @retval RTEMS_INVALID_NAME The name is invalid.
  *  @retval RTEMS_INVALID_ADDRESS The id pointer is NULL, the internal start
  *  address is not aligned, or the external start address is not aligned.
  *  @retval RTEMS_TOO_MANY Cannot create port object.


>    */
>   rtems_status_code rtems_port_create(
>     rtems_name    name,


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