[PATCH v2] c-user: Generate I/O Manager documentation

Tue Oct 6 08:11:09 UTC 2020

On 05/10/2020 18:10, Gedare Bloom wrote:

> On Mon, Oct 5, 2020 at 8:40 AM Sebastian Huber
> <sebastian.huber at embedded-brains.de>  wrote:
>> The manager documentation is a consolidation of the comments in Doxygen
>> markup and the documentation sources in Sphinx markup.  The
>> documentation was transfered to interface specification items.  This
>> header file was generated from the items by a script.
>>
>> Update #3993.
>> ---
>> v2:
>>
>> * Add comments to mention the specification items which produced a
>>    content block.
>>
>> * Preserve original directive order.
>>
>> * Re-order sections so that the description is between the calling
>>    sequence and the return values.
>>
>> * Use .. rubric instead of nested definition lists to fix the vertical
>>    spacing.
>>
>> * Add custom document index entries.
>>
>> Generated PDF:
>>
>> https://ftp.rtems.org/pub/rtems/people/sebh/c-user-6.pdf
>>
>> Generated HTML:
>>
>> https://ftp.rtems.org/pub/rtems/people/sebh/c-user/html/index.html
>>
> I think this is really quite a great start to the automatic
> generation. I have just a couple of comments.
>
>>   c-user/io/directives.rst   | 726 +++++++++++++++++++++----------------
>>   c-user/io/introduction.rst |  64 +++-
>>   2 files changed, 472 insertions(+), 318 deletions(-)
>>
>> diff --git a/c-user/io/directives.rst b/c-user/io/directives.rst
>> index d3098cb..8bf5aea 100644
>> --- a/c-user/io/directives.rst
>> +++ b/c-user/io/directives.rst
>> @@ -1,421 +1,537 @@
>>   .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
>>   .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
>>
>> +.. This file was automatically generated.  Do not edit it manually.
>> +.. Please have a look at
>> +..
>> +..https://docs.rtems.org/branches/master/eng/req/howto.html
>> +..
>> +.. for information how to maintain and re-generate this file.
> "information about how"
> "regenerate"
>
> I know we have the input files listed below now, but maybe it makes
> sense to generate a "transcript" of all the input files here as a
> block of comments?
I added the comment block from Chris.
>
>> +
>> +.. _IOManagerDirectives:
>> +
>>   Directives
>>   ==========
>>
>> -This section details the I/O manager's directives.  A subsection is dedicated
>> -to each of this manager's directives and describes the calling sequence,
>> -related constants, usage, and status codes.
>> +.. Generated from spec:/rtems/io/if/register-driver
>>
>> -.. raw:: latex
>> +.. index:: rtems_io_register_driver()
>> +.. index:: register a device driver
>>
>> -   \clearpage
> In the original docs, there is a page break on each new directive
> including the first one. I guess now since the boilerplate text
> description of Directives has been dropped it would just be a blank
> page with Directives on it. This may be a minor point of
> inconsistency. I think it looks fine without the page break since
> there is no additional text. Joel?
I can also add a boilerplate text and clear the page before the first 
directive.
>
>> +.. _InterfaceRtemsIoRegisterDriver:
>>
>> -.. index:: register a device driver
>> -.. index:: rtems_io_register_driver
>> -
>> -.. _rtems_io_register_driver:
>> -
>> -IO_REGISTER_DRIVER - Register a device driver
>> ----------------------------------------------
>> -
>> -CALLING SEQUENCE:
>> -    .. code-block:: c
>> -
>> -        rtems_status_code rtems_io_register_driver(
>> -            rtems_device_major_number   major,
>> -            rtems_driver_address_table *driver_table,
>> -            rtems_device_major_number  *registered_major
>> -        );
>> -
>> -DIRECTIVE STATUS CODES:
>> -    .. list-table::
>> -     :class: rtems-table
>> -
>> -     * - ``RTEMS_SUCCESSFUL``
>> -       - successfully registered
>> -     * - ``RTEMS_INVALID_ADDRESS``
>> -       - invalid registered major pointer
>> -     * - ``RTEMS_INVALID_ADDRESS``
>> -       - invalid driver table
>> -     * - ``RTEMS_INVALID_NUMBER``
>> -       - invalid major device number
>> -     * - ``RTEMS_TOO_MANY``
>> -       - no available major device table slot
>> -     * - ``RTEMS_RESOURCE_IN_USE``
>> -       - major device number entry in use
>> -
>> -DESCRIPTION:
>> -    This directive attempts to add a new device driver to the Device Driver
>> -    Table. The user can specify a specific major device number via the
>> -    directive's ``major`` parameter, or let the registration routine find the
>> -    next available major device number by specifing a major number of
>> -    ``0``. The selected major device number is returned via the
>> -    ``registered_major`` directive parameter. The directive automatically
>> -    allocation major device numbers from the highest value down.
>> -
>> -    This directive automatically invokes the ``IO_INITIALIZE`` directive if the
>> -    driver address table has an initialization and open entry.
>> -
>> -    The directive returns ``RTEMS_TOO_MANY`` if Device Driver Table is full,
>> -    and ``RTEMS_RESOURCE_IN_USE`` if a specific major device number is
>> -    requested and it is already in use.
>> -
>> -NOTES:
>> -    The Device Driver Table size is specified in the Configuration Table
>> -    condiguration. This needs to be set to maximum size the application
>> -    requires.
>> +rtems_io_register_driver()
>> +--------------------------
>> +
>> +Registers and initializes the device with the specified device driver address
>> +table and device major number in the Device Driver Table.
>> +
>> +.. rubric:: CALLING SEQUENCE:
>> +
>> +.. code-block:: c
>> +
>> +    rtems_status_code rtems_io_register_driver(
>> +      rtems_device_major_number         major,
>> +      const rtems_driver_address_table *driver_table,
>> +      rtems_device_major_number        *registered_major
>> +    );
>> +
>> +.. rubric:: DIRECTIVE PARAMETERS:
> More a question for Joel, the original subheadings here include
> "DIRECTIVE" but all of this is nested underneath Directives.
> Should/Can we simplify these? then this would be "PARAMETERS"
>
>> +
>> +major
>> +    This parameter is the device major number.  Use a value of zero to let the
>> +    system obtain a device major number automatically.
>> +
>> +driver_table
>> +    This parameter is the device driver address table.
>> +
>> +registered_major
>> +    This parameter is the pointer to a device major number variable.  The
>> +    device major number of the registered device will be stored in this
>> +    variable, in case of a successful operation.
>> +
>> +.. rubric:: DIRECTIVE RETURN VALUES:
> and "RETURN VALUES"
This is easy to change. Dropping the DIRECTIVE would be in line with the 
Doxygen output.