[PATCH 0/1] c-user: Generate I/O Manager documentation
sebastian.huber at embedded-brains.de
Thu Oct 1 05:01:52 UTC 2020
On 01/10/2020 06:11, Chris Johns wrote:
> On 30/9/20 12:59 am, Sebastian Huber wrote:
>> This is the first generated documentation of a manager. For the PDF
>> output please have a look at:
>> Please review the layout. I changed the layout to use definition lists
>> instead of tables. The benefit of definition lists is that the layout
>> of longer text paragraphs is much nicer compared to tables (at least for
>> the PDF output).
>> Sebastian Huber (1):
>> c-user: Generate I/O Manager documentation
>> c-user/io/directives.rst | 550 ++++++++++++++++++-------------------
>> c-user/io/introduction.rst | 37 ++-
>> 2 files changed, 295 insertions(+), 292 deletions(-)
> My comments are only about the PDF. I would like to see the HTML as well if that
> is OK?
I will upload the HTML for the v2 of the patch.
> Where is the source of this generated documentation? I would like to review that
> side of things and how it is generated before I am OK with this change.
The documentation source for the IO Manager is here:
> The headings have changed. For example:
> 20.4.1 IO_REGISTER_DRIVER - Register a device driver
> 20.4.1 rtems_io_close()
> I am OK with the change as the bookmarks are much more useful but I think Joel
> needs to say this is OK. These names go back a long way and carry a lot of history.
I think this makes it easer to find the directive documentation.
> The order the directives are in has changed. The IO Manager's directives are
> currently in order of use by a user. What defines the order now?
The order is now alphabetical. I think this is a bit easier for
newcomers which know the alphabet but not necessarily the usual use by a
> The formatting around 'DIRECTIVE RETURN VALUES:' needs fixing. There is vertical
> space after the heading but not before. It looks to me like the heading type is
> broken as 'CALLING SEQUENCE:' etc also appears to have the same vertical spacing.
> Why change 'DIRECTIVE STATUS CODES:' to 'DIRECTIVE RETURN VALUES:'?
This is a more general term, for example here status code doesn't fit well:
> There is description text after the directive section heading and then there is
> a 'DESCRIPTION: section. This seems wrong to me.
After the section heading is the brief description (in Doxygen @brief)
in the DESCRIPTION section is the long description.
> The change from the status code
> table to the list is welcome, those tables were a pain to get right but the
> description now looks lost after them. I do not know what would work here as the
> call sequence at the start is something I like. Is it OK to have the call seq
> then the description then the args and return values?
No problem, it just have to exchange a couple of lines in the generator
> I do not know as a long
> description moves the call seq away from the top. Do the 'NOTES:' follow the
> description around?
What do you mean with "follow the description around"?
> There needs to be a page break after each directive. That is a new directive
> should start on a new page in the PDF format. I think there is a piece of Tex
> inserted to do this.
Ok, I can add this in v2.
Sebastian Huber, embedded brains GmbH
Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone : +49 89 189 47 41-16
Fax : +49 89 189 47 41-09
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.
More information about the devel