[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek,
> 
> In message <201209252246.10322.marex at denx.de> you wrote:
> > I've had a discussion with Wolfgang just now about U-Boot coding style. I
> > tried using KernelDoc in a patch, which is not part of the U-Boot Coding
> > Style now, thus it was rejected.
> > 
> > I really like the idea of annotating functions with proper description,
> > thus I would like to ask, can we reach a general agreement and start
> > using kerneldoc in U-Boot to annotate functions and possibly generate
> > documentation? Or shall we use anything else?
> > 
> > Or any other annotation stuff? Doxygen style? Shall it be optional or
> > mandatory?
> 
> Unfortunately the important (to me) part of our discussion is
> presented here only in the last half sentence...
> 
> The points I was trying to make was this:
> 
>  - If we introdue any documentation system, we should do this
>    "officially", not sneak it in with some patch here and there.

Yes

>  - The first thing we should define is what we want to use it for,
>    i.  e. the purpose.

1) Know what every single function does and what do it's arguments mean, so we 
have properly documented code and every time you hack on something, you won't 
need to do guesswork. This is true especially for some larger functions.
2) To automatically generated code documentation, maybe in HTML format, and put 
it on the webserver. Some people might find it useful.

I myself like 1) more than 2), 2) is not so important for me.

>  - When introducing something, we should also agree on a policy and
>    guidelines how we want to see it used.
> 
> Questions that need to be answered include:
> 
> - What is the goal we want to acchieve?  Complete documentation of all
>   U-Boot code?  Documentation of some sub-system?  ... ?

The former is the ultimate goal, yes. It should have been from the begining. I 
just recently figured out how important it is to have a proper documentation 
(yes, during the DM).

> - Will we make this mandatory?  So that we will reject all new code
>   that is not documented according to kernel-doc rules?

Yes please, make it mandatory. Otherwise people won't obey and the documentation 
will suffer ... and all this would be meaningless.

> - If so, what does that mean for patches that touch existing code?

Ask the current custodian to annotate their code.

>   If I change the major part of an existing function (without changing
>   it's calling interface), am I obligued to add kernel-doc comments?

Yes. Even though major vs. minor change seems pretty vague, common sense shall 
be applied here.

>   If I change the calling interface, must I add documentation then?

Of course, yes.

> - What sort of documentation do we generate?

None for starters, since it will be incomplete. I would postpone the generation 
as a stage 2 here.

> How can we make clear
>   that for a long, long time it will cover only a small fraction of
>   the actual code, eventually even parts of some source files?

Pardon me, but I don't follow here. It will certainly for a while cover only 
small parts of U-Boot code. We need something like "kernel-janitors" here :-)

> - Who will be responsible for maintaining the documentation?

I believe for now we should only focus on using this as a standardized method of 
anotating functions. The reviewer of the patch shall check if the patch is 
correct incl. the documentation, as usual.

> For
>   making sure it gives a usable result, it looks more or less
>   consistent?

Reviewer. The documentation generation shall be postponed.

> - What about internationalization?  Who will do the translations? ;-)
> 
> Best regards,
> 
> Wolfgang Denk

Best regards,
Marek Vasut