Comments in spec files in rtems.git

[Sebastian Huber]

On 22/09/2020 03:38, Chris Johns wrote:
> On 21/9/20 12:35 am, Sebastian Huber wrote:
>> On 19/09/2020 02:43, Chris Johns wrote:
>>> Hi,
>>>
>>> Can comments be added to the .yml files under specs in rtems.git?
>> the problem with comments in YAML files is that they are not preserved if you
>> parse the files and write them back.
> Could we have a comment block that is a YAML field? Hmm I see a description
> field, I wonder if that could serve this purpose. Is that field available in all
> files?

The attributes for each type are documented here:

https://docs.rtems.org/branches/master/eng/req/items.html#spectypebuilditemtype

Yes, we could add a comment attribute. Ideally, we don't need comments.

>
>>> I was looking over a few files and wonder if some comments would help.
>> Could you give an example? Maybe we could add an attribute for this.
> I picked this file at random ...
>
> https://git.rtems.org/rtems/tree/spec/build/bsps/optabi.yml
>
> What does it do? It is needed in all BSP build files?
>
> While this file ...
>
> https://git.rtems.org/rtems/tree/spec/build/bsps/tst.yml
>
> ... has something which indicates what it is for and I assume I could edit this
> and add more detail, for example it is automatically picked up or it needs to be
> included in XXX.

I am not sure if it is the right approach to pick up a random file and 
expect that it explains all aspects why it is there in the from of a 
comment. The documentation should start with a use case, e.g. how can I 
add a BSP:

https://docs.rtems.org/branches/master/eng/build-system.html#how-to

>
> Then in a BSP ...
>
> https://git.rtems.org/rtems/tree/spec/build/bsps/powerpc/mvme5500/bspmvme5500.yml
>
> ... says nothing about the board, has no links.

We could add documentation attributes to the BSPs and use this 
information to generate the BSP chapter in the user manual.

This file has links to other items.

>
> There is no way to see the dependencies between all the files unless you build a
> mental image ...
>
> https://git.rtems.org/rtems/tree/spec/build/bsps/powerpc/mvme5500/bspmvme5500.yml
>
> and ../../opto2
Yes, we need some diagnostic commands for the build system. One could 
visualize the dependency graph of a BSP, a library, etc.
>
> What does this file do ...
>
> https://git.rtems.org/rtems/tree/spec/build/bsps/powerpc/motorola_powerpc/qemufakerom.yml
>
> ?

Why do you need the qemu_fakerom.* files? This should be explained here:

https://docs.rtems.org/branches/master/user/bsps/bsps-powerpc.html#motorola-powerpc

A user should not need to dig into build item comments to know what to 
do with installed files of a BSP.