[U-Boot] KernelDoc

[Joe Hershberger]

Hi Marek,

On Wed, Sep 26, 2012 at 10:26 AM, Marek Vasut <marex at denx.de> wrote:
> 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.

I agree that 2 is not very important, but 1 is helpful.

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

I think mandatory should only be for newly added functions.  There is
already enough burden on touching existing code wrt checkpatch.  The
reviewer can feel free to recommend documentation if appropriate...
possibly even drafting the docs.

>> - If so, what does that mean for patches that touch existing code?
>
> Ask the current custodian to annotate their code.

This seems like a nice approach to get pretty good coverage for areas
that have maintainers... it won't help for most of the common things
(unless you are suggesting that WD has an awful lot to document).

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

And hence should not be mandatory to make the requirement criteria clear.

>>   If I change the calling interface, must I add documentation then?
>
> Of course, yes.

Agreed.

[...]

-Joe