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

[Chris Johns]

On 1/10/20 3:01 pm, Sebastian Huber wrote:
> On 01/10/2020 06:11, Chris Johns wrote:
>> On 30/9/20 12:59 am, Sebastian Huber wrote:
>> 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

Thanks.

This file is complicated and I am concerned this has raised the bar to a level
that inhibits it being maintained at a community level. The YAML file seems to
be a programming language of it's own where I need to know other pieces, for
example:

    - ${device-major-number:/name} ${.:/params[0]/name}

I have no idea if this is YAML or a preprocessor layer you have added. In this bit:

    value: ${../../status/if/successful:/name}

the double dots look like a directory so now we have relative paths in the files
and this is fragile because any internal movement of the files breaks these
links. We do not use those sorts of path in C code for headers for good reason
and I think the same rational applies here. The string `status/if/successful`
should be unique enough to be a reliable key.

Another issue is crosstalk between the generated documentation, tests, API and
anything else. I feel I would need to understand those parts so I could
confidently make changes. I would not want to unintentionally break something else.

On the topic of making changes the only way I could contribute once this is
merged is to alter the generated files. This is not helpful and I also think not
the intention. It raises a couple of issues. Does the generation process check
to see if a generated file has been touched since last generated so downstream
changes are not lost? Second, I am concern you end up marooning yourself with
the sole maintenance effort beyond the qual project you are on and that also
means we are dependent on you. This does not pass the bus test.

I understand these are API interfaces that should not or do not change but this
is documentation and we can always make that better. For example I have wanted
to add code fragments to the calls, a sort of copy and paste template. I could
add this with little or no extra effort to the sphinx source however I have no
idea where to start with these YAML files.

>> 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.

Sorry I do not agree. I agree with Joel the current order is good.

>> 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

OK

>> 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"?

If the description moves do notes always appear after it?

Chris