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

[Gedare Bloom]

I imagine there are repeated issues like this. These may be hard to
generalize for students to accomplish in GCI tasks. I believe what we are
getting is better than what we had, and we can make the minor fixes like
making proper sentences, relabelling parameters properly, etc as we go.


On Thu, Dec 6, 2012 at 3:24 AM, Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> 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<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<http://www.rtems.org/mailman/listinfo/rtems-devel>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20121206/e0f06afd/attachment-0001.html>