Purpose of rtems_device_driver?

[Sebastian Huber]

Hello Peter,

On 29/09/2020 20:01, Peter Dufault wrote:
>> On Sep 29, 2020, at 10:13 , Joel Sherrill<joel at rtems.org>  wrote:
>>
>>
>>
>> On Tue, Sep 29, 2020 at 8:54 AM Sebastian Huber<sebastian.huber at embedded-brains.de>  wrote:
>> On 29/09/2020 15:47, Sebastian Huber wrote:
>>
>>> On 29/09/2020 15:42, Joel Sherrill wrote:
>>>
>>>> On Tue, Sep 29, 2020 at 8:37 AM Sebastian Huber
>>>> <sebastian.huber at embedded-brains.de
>>>> <mailto:sebastian.huber at embedded-brains.de>> wrote:
>>>>
>>>>      Hello,
>>>>
>>>>      I work currently on the documentation of the IO Manager. What is the
>>>>      purpose of
>>>>
>>>>      typedef rtems_status_code rtems_device_driver;
>>>>
>>>>      ?
>>>>
>>>>      For me this looks a bit like camouflage.
>>>>
>>>>
>>>> No. It is a use of typedef to make the purpose of the method clear.
>>>>
>>>> You have nibbled at these for years. There were at least types for
>>>> Classic Tasks, ASRs, and TSRs at one point.
>>> Yes, the typedefs to void.
>>>> If this is the last one, I'm not going to fight it. This isn't the
>>>> hill I am
>>>> going to die on.
>>> I am not suggesting to remove them although I find these typedefs
>>> pretty odd. I just look for some documentation text.
>> What about this:
>>
>> /**
>>    * @ingroup RTEMSAPIClassicIO
>>    *
>>    * @brief This type shall be used in device driver entry declarations and
>>    *   definitions.
>>    *
>>    * Device driver entries return an #rtems_status_code status code. This
>> type
>>    * definition helps to document device driver entries in the source code.
>>    */
>> typedef rtems_status_code rtems_device_driver;
>>
>> That's more than sufficient.
>>
>> Thanks.
> This typedef is odd.  Unless I'm missing a fine-point.
>
> If the typedef is, and always will remain, "rtems_status_code" I would not use a typedef.

I don't want to change the API, I just want to document it. However, I 
am not sure if we should advertise the use of these typedefs in 
application code:

typedef rtems_status_code rtems_device_driver;

typedef void rtems_task;

typedef void rtems_timer_service_routine;

typedef void rtems_asr;

If you consistently use these types, then for example you can grep for 
"\<rtems_task\>" and find all task entry functions. I guess some people 
like this, other don't like it.

>
> The RTEMS API documentation is moving to Doxygen (and more formally than that given Sebastian's ESA work). Using a typedef to indicate a function is part of a device driver as "documentation" is not a good idea.

The API documentation is not really moving to Doxygen. It moves to specification items after consolidation and then it moves back to Doxygen and the manuals. A common data set and the generation through a script ensures that the documentation in both parts is consistent.