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:
https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
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:
https://git.rtems.org/rtems-central/tree/spec/rtems/io/if
The headings have changed. For example:
20.4.1 IO_REGISTER_DRIVER - Register a device driver
to:
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
user order.
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:
https://docs.rtems.org/branches/master/c-user/scheduling-concepts/directives.html#scheduler-get-processor-maximum-get-processor-maximum
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
script.
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.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
