Hello Peter,
On 29/09/2020 20:01, Peter Dufault wrote:
On Sep 29, 2020, at 10:13 , Joel Sherrill<j...@rtems.org> wrote:
On Tue, Sep 29, 2020 at 8:54 AM Sebastian
Huber<sebastian.hu...@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.hu...@embedded-brains.de
<mailto:sebastian.hu...@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.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
