[U-Boot] KernelDoc

[U-Boot] KernelDoc

[Marek Vasut]

Hi all!

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?

See [1] in Linux kernel tree for what I mean.

[1] Documentation/kernel-doc-nano-HOWTO.txt

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Prabhakar Lad]

Hi Marek,

On Wed, Sep 26, 2012 at 2:16 AM, Marek Vasut <marex@denx.de> wrote:
> Hi all!
>
> 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?
>
 +1 for kerneldoc.

Regards,
--Prabhakar Lad

> Or any other annotation stuff? Doxygen style? Shall it be optional or mandatory?
>
> See [1] in Linux kernel tree for what I mean.
>
> [1] Documentation/kernel-doc-nano-HOWTO.txt
>
> Best regards,
> Marek Vasut
> _______________________________________________
> U-Boot mailing list
> U-Boot at lists.denx.de
> http://lists.denx.de/mailman/listinfo/u-boot

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Prabhakar Lad,

In message <CA+V-a8vZ-715eL1MNvxhYCGNWv5YSGuoNn5hZQeMFN5ZKtpKMQ@mail.gmail.com> you wrote:
> 
> > 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?
> >
>  +1 for kerneldoc.

Could you please explain what exactly your vote is supposed to mean?

Shall it become mandatory for all new code submitted?  Shall all
patches submitted from now on be rejected when the code they touch is
not accordingly documented?

What is the goal you see for using this?


I'm afraid I don't know what exactly you voted for...

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
How many QA engineers does it take to screw in a lightbulb? 3:  1  to
screw it in and 2 to say "I told you so" when it doesn't work.

[U-Boot] KernelDoc

[Prabhakar Lad]

Hi Wolfgang,

On Wed, Sep 26, 2012 at 12:42 PM, Wolfgang Denk <wd@denx.de> wrote:
> Dear Prabhakar Lad,
>
> In message <CA+V-a8vZ-715eL1MNvxhYCGNWv5YSGuoNn5hZQeMFN5ZKtpKMQ@mail.gmail.com> you wrote:
>>
>> > 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?
>> >
>>  +1 for kerneldoc.
>
> Could you please explain what exactly your vote is supposed to mean?
>
My vote was for using kerneldoc to annotate functions and generate documentation

> Shall it become mandatory for all new code submitted?  Shall all
> patches submitted from now on be rejected when the code they touch is
> not accordingly documented?
>
Not for all the patches I would say. This should be compulsory for the
patches touching some generic code (for example the common folder).

> What is the goal you see for using this?
>
Readability of the code will increase.

Regards,
--Prabhakar Lad

>
> I'm afraid I don't know what exactly you voted for...
>
> Best regards,
>
> Wolfgang Denk
>
> --
> DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
> HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
> Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
> How many QA engineers does it take to screw in a lightbulb? 3:  1  to
> screw it in and 2 to say "I told you so" when it doesn't work.

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Prabhakar Lad,

In message <CA+V-a8ujwAdpKKtm+7GsC7DRB5DtCFUhE+7Jn69sBVj5kz+1Dg@mail.gmail.com> you wrote:
> 
> > Could you please explain what exactly your vote is supposed to mean?
> >
> My vote was for using kerneldoc to annotate functions and generate documentation
...
> Readability of the code will increase.

Which sort of documentation would you want to generate?

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
Military secrets are the most fleeting of all.
	-- Spock, "The Enterprise Incident", stardate 5027.4

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek,

In message <201209252246.10322.marex@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.

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

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

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

- If so, what does that mean for patches that touch existing 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?
  If I change the calling interface, must I add documentation then?

- What sort of documentation do we generate?  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?

- Who will be responsible for maintaining the documentation?  For
  making sure it gives a usable result, it looks more or less
  consistent?

- What about internationalization?  Who will do the translations? ;-)

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
When you die, the first thing you lose is your life. The  next  thing
is the illusions.                       - Terry Pratchett, _Pyramids_

[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek,
> 
> In message <201209252246.10322.marex@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

[U-Boot] KernelDoc

[Joe Hershberger]

Hi Marek,

On Wed, Sep 26, 2012 at 10:26 AM, Marek Vasut <marex@denx.de> wrote:
> Dear Wolfgang Denk,
>
>> Dear Marek,
>>
>> In message <201209252246.10322.marex@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

[U-Boot] KernelDoc

[Marek Vasut]

Dear Joe Hershberger,

[..]

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

Pardon my wording, this is what I had in mind.

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

+1
 
> >> - 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).

With the DM, I slowly started to claim this role :-(

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

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek,

In message <201209261726.55611.marex@denx.de> you wrote:
> 
> > - 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.

Judge from previous experience: how well will this work?  And what do
we do if it doesn't work?  Or if you want to get your critical bug fix
in now, but the custodian promises a doc patch for half a year later?

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

Didn't we agree that we want to make it easier for people to
contribute code?  If somebody who just wants to improve a small detail
in the code is now not only enforced to fix the coding style, but
_also_ document the whole file, this will probably not exactly attract
new contributors.


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

Don't, that will fire back later, then.

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

I agree.  We could need all kind of help for at least a dozen of
tasks.  Where do we find these?  And for free?

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

And missing or incorrect documentation would cause the patch to be
rejected?


Can such checking (all functions have a kernel-doc comment, which
covers the return value and all arguments) be done automatically, say
throuch checkpatch?


Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
Intuition, however illogical, is recognized as a command prerogative.
	-- Kirk, "Obsession", stardate 3620.7

[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek,
> 
> In message <201209261726.55611.marex@denx.de> you wrote:
> > > - 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.
> 
> Judge from previous experience: how well will this work?

I would hate to make anyone unhappy by commenting on this ;-)

> And what do we do if it doesn't work?

Is there anything we can do? It's a community project, the project is only as 
good as the community.

> Or if you want to get your critical bug fix
> in now, but the custodian promises a doc patch for half a year later?

I cannot parse this. I agree the critical fix has a high-prio.

> > >   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.
> 
> Didn't we agree that we want to make it easier for people to
> contribute code?  If somebody who just wants to improve a small detail
> in the code is now not only enforced to fix the coding style, but
> _also_ document the whole file, this will probably not exactly attract
> new contributors.

Of course. But if someone fixes the calling interface, how are we supposed to 
know what does new parameter do? It must be documented.

> > > - 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.
> 
> Don't, that will fire back later, then.
> 
> > > 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 :-)
> 
> I agree.  We could need all kind of help for at least a dozen of
> tasks.  Where do we find these?  And for free?

This is a problem we have for a while.

> > > - 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.
> 
> And missing or incorrect documentation would cause the patch to be
> rejected?

Yes.

> Can such checking (all functions have a kernel-doc comment, which
> covers the return value and all arguments) be done automatically, say
> throuch checkpatch?

I would love to see this.

> Best regards,
> 
> Wolfgang Denk

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek,

In message <201209262158.48495.marex@denx.de> you wrote:
> 
> > Or if you want to get your critical bug fix
> > in now, but the custodian promises a doc patch for half a year later?
> 
> I cannot parse this. I agree the critical fix has a high-prio.

You suggested that including kernel-doc comments was mandatory for
patches to be accepted.  And that the respective maintainer should be
asked to fix the documentation for his code if needed. So we have to
wait for this maintainer before the patch goes in?

Ah, you say the fix has "high-prio".  So we are defining exceptions
from the rules?  We should document these.


> > Didn't we agree that we want to make it easier for people to
> > contribute code?  If somebody who just wants to improve a small detail
> > in the code is now not only enforced to fix the coding style, but
> > _also_ document the whole file, this will probably not exactly attract
> > new contributors.
> 
> Of course. But if someone fixes the calling interface, how are we supposed to 
> know what does new parameter do? It must be documented.

How do we do such today?

I think is kind of unfair to expect such efforts for some basicly
unrelated changes.  If I were in such a situation, I'd feel tempted to
throw the towel.


> > > only small parts of U-Boot code. We need something like
> > > "kernel-janitors" here :-)
> > 
> > I agree.  We could need all kind of help for at least a dozen of
> > tasks.  Where do we find these?  And for free?
> 
> This is a problem we have for a while.

Still looking for ideas, sugestions, volunteers...

> > And missing or incorrect documentation would cause the patch to be
> > rejected?
> 
> Yes.

OK, then such new policy needs to be clearly communicated and
documented.

> > Can such checking (all functions have a kernel-doc comment, which
> > covers the return value and all arguments) be done automatically, say
> > throuch checkpatch?
> 
> I would love to see this.

Is anything like this available anywhere?

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
"At least they're __________EXPERIENCED incompetents"

[U-Boot] KernelDoc

[Tom Rini]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 09/26/12 13:57, Wolfgang Denk wrote:

[snip]
>>> Can such checking (all functions have a kernel-doc comment, 
>>> which covers the return value and all arguments) be done 
>>> automatically, say throuch checkpatch?
>> 
>> I would love to see this.
> 
> Is anything like this available anywhere?

Wire building the docs into patman, that'll cover big series which
ought to be using it, at least.  It's a thought..

- -- 
Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://www.enigmail.net/

iQIcBAEBAgAGBQJQY3QbAAoJENk4IS6UOR1WhpEP/RB0HQxOzFsTzl3ycvlj+NyA
jxSndrPbevwW97ccvgrhfWYgEjG/dUoC+VtiBUvsYupLEL5y02NriblF0spnEfpO
UA5wuucZX45EQ1rJvfVS1Rg2hiOeM4L3GxN8KqOCLE7X6rQV5PCS+4X2XvE3eGVx
vUKoUdLCphlf0cpxKMLNXLZCrZhRwaDaJK9XghuWsYKkGtRiwDoo2qhl9AepJpaN
INtI1aOlm40An5Ql32Y2dHXJMd+/W2dXqYzG/Jy1oqJI35UmPiSDP/Nr0O96Pe/G
aO1Izo8aogEDkJRr6KVY5PiT9K3epFBBkO+LsQbOzB/KgUkH88yTk/dC0STXKEV0
LTwrp1aL8ISZ1DIWQ+EXBTM6mEvnCjOmj3+JrvetfcW5r9INqhWiytRtG/bshwJf
/tKkM6X+5AujToNdZcfqxrb7o94KB3vQlU88f/HKZT39l0kxe61oXgxm1SPC64Wn
Fpmd1NY2kQv9jm/xYa4Sa3dguk1uf89JAZfqfbvEzgOzkRCMTAPuAzSdJaVjzIBr
B3HnjwWrfsI7XcMYme60nfI2NOx6aJDhMOvUrvOQFavFdeaL7RWUDIkStNYa7ZrW
+mFg4JjcKNnPCCyV7W/xWT/MWnxzgOAwKcfx328XoCdCQqWx8QLZ7dCBmoF9aUhs
T1K9yLYnshTKcWoe2oFk
=F53o
-----END PGP SIGNATURE-----

[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek,
> 
> In message <201209262158.48495.marex@denx.de> you wrote:
> > > Or if you want to get your critical bug fix
> > > in now, but the custodian promises a doc patch for half a year later?
> > 
> > I cannot parse this. I agree the critical fix has a high-prio.
> 
> You suggested that including kernel-doc comments was mandatory for
> patches to be accepted.  And that the respective maintainer should be
> asked to fix the documentation for his code if needed. So we have to
> wait for this maintainer before the patch goes in?
> 
> Ah, you say the fix has "high-prio".  So we are defining exceptions
> from the rules?  We should document these.

Agreed!

> > > Didn't we agree that we want to make it easier for people to
> > > contribute code?  If somebody who just wants to improve a small detail
> > > in the code is now not only enforced to fix the coding style, but
> > > _also_ document the whole file, this will probably not exactly attract
> > > new contributors.
> > 
> > Of course. But if someone fixes the calling interface, how are we
> > supposed to know what does new parameter do? It must be documented.
> 
> How do we do such today?

I think there's no rule for that.

> I think is kind of unfair to expect such efforts for some basicly
> unrelated changes.  If I were in such a situation, I'd feel tempted to
> throw the towel.

Why would you do so ... you change interface, you document it.

> > > > only small parts of U-Boot code. We need something like
> > > > "kernel-janitors" here :-)
> > > 
> > > I agree.  We could need all kind of help for at least a dozen of
> > > tasks.  Where do we find these?  And for free?
> > 
> > This is a problem we have for a while.
> 
> Still looking for ideas, sugestions, volunteers...

+1

> > > And missing or incorrect documentation would cause the patch to be
> > > rejected?
> > 
> > Yes.
> 
> OK, then such new policy needs to be clearly communicated and
> documented.

+1

> > > Can such checking (all functions have a kernel-doc comment, which
> > > covers the return value and all arguments) be done automatically, say
> > > throuch checkpatch?
> > 
> > I would love to see this.
> 
> Is anything like this available anywhere?

Like Tom said, compile the docs and see if they are produced ok ... otherwise, 
dunno.

> Best regards,
> 
> Wolfgang Denk

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek Vasut,

In message <201209270138.12860.marex@denx.de> you wrote:
> 
> > I think is kind of unfair to expect such efforts for some basicly
> > unrelated changes.  If I were in such a situation, I'd feel tempted to
> > throw the towel.
> 
> Why would you do so ... you change interface, you document it.

Having to document not only my change, but all the rest of the source
file as well may mean I spend way more work on this doc task than on
the actual fix.

And while I may well understand the area I meddled with, I may not
easily understand the rest of the code, so this is twice hard and time
consuming.

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
The language provides a programmer with a set of conceptual tools; if
these are inadequate for the task, they will simply be  ignored.  For
example, seriously restricting the concept of a pointer simply forces
the  programmer  to use a vector plus integer arithmetic to implement
structures, pointer, etc. Good  design  and  the  absence  of  errors
cannot  be guaranteed by mere language features. - Bjarne Stroustrup,
"The C++ Programming Language"

[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek Vasut,
> 
> In message <201209270138.12860.marex@denx.de> you wrote:
> > > I think is kind of unfair to expect such efforts for some basicly
> > > unrelated changes.  If I were in such a situation, I'd feel tempted to
> > > throw the towel.
> > 
> > Why would you do so ... you change interface, you document it.
> 
> Having to document not only my change, but all the rest of the source
> file as well may mean I spend way more work on this doc task than on
> the actual fix.
> 
> And while I may well understand the area I meddled with, I may not
> easily understand the rest of the code, so this is twice hard and time
> consuming.

Agreed, not the whole file. But, can you check the rules I tried to outline?

> Best regards,
> 
> Wolfgang Denk

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek Vasut,

In message <201210011107.45164.marex@denx.de> you wrote:
> 
> Agreed, not the whole file. But, can you check the rules I tried to outline?

Is there a summary somewhere?  Something we could add to the wiki?

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
No problem is insoluble.
	-- Dr. Janet Wallace, "The Deadly Years", stardate 3479.4

[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek Vasut,
> 
> In message <201210011107.45164.marex@denx.de> you wrote:
> > Agreed, not the whole file. But, can you check the rules I tried to
> > outline?
> 
> Is there a summary somewhere?  Something we could add to the wiki?

I sent this on friday:

So I've been hacking on it for a bit, see the first stab at [1]. As for the 
ruleset, I propose this addition for the Wiki [2]:

-->8--

U-Boot code documentation
=========================

U-Boot adopted the kernel-doc annotation style, this is the only exception from 
multi-line comment rule of Coding Style. While not mandatory, adding 
documentation is strongly advised. The Linux kernel kernel-doc document [3] 
appliest with no changes.

--8<--

[1] http://twilight.ponies.cz/kerneldoc/
[2] http://www.denx.de/wiki/U-Boot/CodingStyle
[3] 
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/kernel-
doc-nano-HOWTO.txt

> Best regards,
> 
> Wolfgang Denk

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Tom Rini]

On Mon, Oct 01, 2012 at 12:37:26PM +0200, Marek Vasut wrote:
> Dear Wolfgang Denk,
> 
> > Dear Marek Vasut,
> > 
> > In message <201210011107.45164.marex@denx.de> you wrote:
> > > Agreed, not the whole file. But, can you check the rules I tried to
> > > outline?
> > 
> > Is there a summary somewhere?  Something we could add to the wiki?
> 
> I sent this on friday:
> 
> So I've been hacking on it for a bit, see the first stab at [1]. As for the 
> ruleset, I propose this addition for the Wiki [2]:
> 
> -->8--
> 
> U-Boot code documentation
> =========================
> 
> U-Boot adopted the kernel-doc annotation style, this is the only exception from 
> multi-line comment rule of Coding Style. While not mandatory, adding 
> documentation is strongly advised. The Linux kernel kernel-doc document [3] 
> appliest with no changes.
> 
> --8<--
> 
> [1] http://twilight.ponies.cz/kerneldoc/
> [2] http://www.denx.de/wiki/U-Boot/CodingStyle
> [3] 
> http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/kernel-
> doc-nano-HOWTO.txt

Make it so.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20121009/b180bd2f/attachment.pgp>

[U-Boot] KernelDoc

[Marek Vasut]

Dear Tom Rini,

> On Mon, Oct 01, 2012 at 12:37:26PM +0200, Marek Vasut wrote:
> > Dear Wolfgang Denk,
> > 
> > > Dear Marek Vasut,
> > > 
> > > In message <201210011107.45164.marex@denx.de> you wrote:
> > > > Agreed, not the whole file. But, can you check the rules I tried to
> > > > outline?
> > > 
> > > Is there a summary somewhere?  Something we could add to the wiki?
> > 
> > I sent this on friday:
> > 
> > So I've been hacking on it for a bit, see the first stab at [1]. As for
> > the ruleset, I propose this addition for the Wiki [2]:
> > 
> > -->8--
> > 
> > U-Boot code documentation
> > =========================
> > 
> > U-Boot adopted the kernel-doc annotation style, this is the only
> > exception from multi-line comment rule of Coding Style. While not
> > mandatory, adding documentation is strongly advised. The Linux kernel
> > kernel-doc document [3] appliest with no changes.
> > 
> > --8<--
> > 
> > [1] http://twilight.ponies.cz/kerneldoc/
> > [2] http://www.denx.de/wiki/U-Boot/CodingStyle
> > [3]
> > http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f
> > =Documentation/kernel- doc-nano-HOWTO.txt
> 
> Make it so.

Let's wait for Wolfgang, I'd like to have his ACK on this please.

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Marek Vasut]

Dear Tom Rini,

> On Mon, Oct 01, 2012 at 12:37:26PM +0200, Marek Vasut wrote:
> > Dear Wolfgang Denk,
> > 
> > > Dear Marek Vasut,
> > > 
> > > In message <201210011107.45164.marex@denx.de> you wrote:
> > > > Agreed, not the whole file. But, can you check the rules I tried to
> > > > outline?
> > > 
> > > Is there a summary somewhere?  Something we could add to the wiki?
> > 
> > I sent this on friday:
> > 
> > So I've been hacking on it for a bit, see the first stab at [1]. As for
> > the ruleset, I propose this addition for the Wiki [2]:
> > 
> > -->8--
> > 
> > U-Boot code documentation
> > =========================
> > 
> > U-Boot adopted the kernel-doc annotation style, this is the only
> > exception from multi-line comment rule of Coding Style. While not
> > mandatory, adding documentation is strongly advised. The Linux kernel
> > kernel-doc document [3] appliest with no changes.
> > 
> > --8<--
> > 
> > [1] http://twilight.ponies.cz/kerneldoc/
> > [2] http://www.denx.de/wiki/U-Boot/CodingStyle
> > [3]
> > http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f
> > =Documentation/kernel- doc-nano-HOWTO.txt
> 
> Make it so.

As -next will be merged into master tomorrow or so, done.

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Tom Rini]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 09/26/12 12:54, Wolfgang Denk wrote:

> Can such checking (all functions have a kernel-doc comment, which 
> covers the return value and all arguments) be done automatically,
> say throuch checkpatch?

It's been a long time but I believe you see those problems when you
generate the docs, but not checkpatch (from a quick skim of the code
in the kernel).

- -- 
Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://www.enigmail.net/

iQIcBAEBAgAGBQJQY17uAAoJENk4IS6UOR1WBw4P+wZRQV9Az8+O3MfkI+jGR0BF
hrt0VRbn9i3EaUPlFsRIE2FSeeTYgSb+F7DY7BYg7H9REkuzCbJgUEmYHguN4F+x
fbq+cH3axkNISs3xnI4Y3GH6jTTdePgT4jWMjMLGjwpiskValEDUwTw+qVkWDtri
AKUBCCpJsjm39Ig94hbhQKr0iLwNQfO4I9itOQVbVtP92+uVN/xR9WGyN1APUrEC
XUAlw+myZE2YFTaSPSceZK/5UHxtQVYTg1VZMmwd5K5ReGvmUWQS+4qpTOFA6XaT
XYmNqw3/UXIhwM07+mfgHvvf+KJm7wRncaBzh8U1SDkaf8p2VaYrNTcLrCoWWIKg
Nv7vTgb4s5avBdRhIdmZpVsOel4srfkBfYn18J8Zhv0fPuf0KGRBHsHTfK+jAJVy
qms02hvnidg5iuwdeNPF+C0tweErxcI8BtDJA2mKBmXzu2REXX1D+uOLdtzLlLeW
8tBbR06lEXeVar42LGQEqfrlcaIKXC+UFBxLnSF/o0ZyP/5Od8WUIGeoK15ZGLhf
BebN3uT3+6RTdIdmiNlpUxvUnsGqaiLHedT8V8gZRtqCrxEhHwB6Q5Gl7Xu1qjMW
kxsc1aYzlJooWEiQZjMR7BxlUTPdgca2GX3wiV6YxhZQIyd3MY14utp2Joglizs1
XjlOSbjGTTIEuTiFh9vO
=9aWt
-----END PGP SIGNATURE-----

[U-Boot] KernelDoc

[Stefan Roese]

On 09/26/2012 09:54 PM, Wolfgang Denk wrote:

<snip>

>>>   If I change the calling interface, must I add documentation then?
>>
>> Of course, yes.
> 
> Didn't we agree that we want to make it easier for people to
> contribute code?  If somebody who just wants to improve a small detail
> in the code is now not only enforced to fix the coding style, but
> _also_ document the whole file, this will probably not exactly attract
> new contributors.

Full ACK.

<snip>

>>> - 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.
> 
> And missing or incorrect documentation would cause the patch to be
> rejected?

Please don't. As you mentioned above, we (in U-Boot) already have very
strict rules making it not easy for especially new developers to push
their changes upstream. I fear that with such a new requirement, more
users / developers will abandon pushing their patches at some time.

BTW: I've done quite some Linux kernel work and never used this
kernel-doc style so far. Its not mandatory in the Linux kernel. Not that
this really matters in regards to U-Boot. But my personal feeling is,
that we shouldn't make it much harder to push patches in U-Boot than in
Linux.

Just my 0.02$.

Thanks,
Stefan

[U-Boot] KernelDoc

[Tom Rini]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 09/26/12 23:19, Stefan Roese wrote:

[snip]
> BTW: I've done quite some Linux kernel work and never used this 
> kernel-doc style so far. Its not mandatory in the Linux kernel. Not
> that this really matters in regards to U-Boot. But my personal
> feeling is, that we shouldn't make it much harder to push patches
> in U-Boot than in Linux.

Exactly.  This gets at the point I was trying to make.  It's not "make
these comments, magically get documentation".  It's "make these
comments, write the rest of your documentation in the right XML
markup, get {pdf,html,man,etc,etc,etc} output".  So the DM work is a
good reason / candidate to add the infrastructure (sine we already
have design docs).  And someone could take the kernel mtdnand
template, update it with verbage about how we shim that in and also
get good docs.  Other subsystems or "big" things could also make use
of this.

- -- 
Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://www.enigmail.net/

iQIcBAEBAgAGBQJQZIw3AAoJENk4IS6UOR1WTaoP/A3zdhlaZ7o7F8GXwPIOiSWT
b/ACtfiBPrFlZnLDMp0SGQ2NSdCwzkH1cL7jSPBbPXfIwefu3rWz4PZ8pQydfhm7
OHp4iiOfPGDc41OXsmQNK8NVxneyhzPRjNLQF6G/VAvALuPkZsD9nDOUxKLgqtEx
MhweRvo52DJTNROAnf+VkoUQ0k/epkCU/vquIKWQbLNg8ACEBQskPFm8Ze6Ix5yA
k0JXhGYjTBSpPdGC2w6qLHbtdWdtHf+R/CER0tpOyml0aLWfZpBt4irqNPI6gdrp
/5lX67k4KZ0wlWUWWcgCfF74Onxp8vavIA5MNcS9NvKuueglKqP+j7q9JP1Vv+7o
2GK3Z+GvFqrTLF84SVS25iC+D98EsOb4fKslieE5rjMTaNakQ3Hw9QTVY6tkypSA
zGlYUK40eKmlt72Xh37vhYRUtSZ+yjGkxEQC3fCLo/WBgTUsM/NGaiPIW0Jn1zA6
/dognravZFpofSY5tF7hkzjV4xhSU4Chq3fe3lBXI3fY4XwOrzNVq+hXGWAEz7fW
e/oTmisJj09sk6KdxS14eejoB4fS5WzuRbTS9b1iDzksqw+Odiud8j5KPM6iVaEb
NPyRLpSJOOgWg5uYXCUyfl67XjnnvmyPyWTrpUancWLPf7bSL7Pn0fJuK0IQNEUN
175m/a86u/PK4vRKjOp8
=EteI
-----END PGP SIGNATURE-----

[U-Boot] KernelDoc

[Fabio Estevam]

On Thu, Sep 27, 2012 at 3:19 AM, Stefan Roese <sr@denx.de> wrote:

> Please don't. As you mentioned above, we (in U-Boot) already have very
> strict rules making it not easy for especially new developers to push
> their changes upstream. I fear that with such a new requirement, more
> users / developers will abandon pushing their patches at some time.
>
> BTW: I've done quite some Linux kernel work and never used this
> kernel-doc style so far. Its not mandatory in the Linux kernel. Not that
> this really matters in regards to U-Boot. But my personal feeling is,
> that we shouldn't make it much harder to push patches in U-Boot than in
> Linux.

Fully agree.

Regards,

Fabio Estevam

[U-Boot] KernelDoc

[Graeme Russ]

Hi All,

A bit late on the bandwagon, but for what it is worth I have thought
any form of officially sanctioned (and encouraged) in-line
documentation would be 'A Good Thing'(tm)

I had a quick look at kerneldoc and doxygen and while doxygen is far
more powerful, it's also a lot less 'natural' as a commenting style.
Besides, we really only have C to worry about, so we don't need to
drag in the overhead of a documentation format that supports every
language under the sun :)

One point I agree on is that we must not make the barrier to entry for
new developers any higher than strictly necessary. For me, I would not
expect to be forced to document anything that was not already
documented - i.e. if I change a function (adding a parameter, changing
it's return value, etc) that was not already kerneldoc'd, I would have
a dummy spit if I was asked to resubmit with complete documentation.

I'm thinking that someone with  Super Saiyan levels of script-fu could
probably automate the addition of kerneldoc stubs with 'undocumented'
text

I really don't mind what the documentation rules are, but the MUST be
on the wiki. One this note, I think we should merge the 'Coding Style'
and  'Patches' pages of the wiki and rename them to something more
obvious like, for example, 'Rules for submitting U-Boot patches'.
Also, I think a regular reminder (say every two weeks) on the mailing
list pointing out the 'developer rules' on the wiki would be good - we
tend to get quite a number of on-off patches from new developers that
don't meet the submission criteria simply because they a blissfully
ignorant of them.

Slightly OT - what is happening with the proposed patch tracker?

Regards,

Graeme

[U-Boot] KernelDoc

[Marek Vasut]

Dear Graeme Russ,

> Hi All,
> 
> A bit late on the bandwagon, but for what it is worth I have thought
> any form of officially sanctioned (and encouraged) in-line
> documentation would be 'A Good Thing'(tm)

+1

> I had a quick look at kerneldoc and doxygen and while doxygen is far
> more powerful, it's also a lot less 'natural' as a commenting style.
> Besides, we really only have C to worry about, so we don't need to
> drag in the overhead of a documentation format that supports every
> language under the sun :)

+1

> One point I agree on is that we must not make the barrier to entry for
> new developers any higher than strictly necessary. For me, I would not
> expect to be forced to document anything that was not already
> documented - i.e. if I change a function (adding a parameter, changing
> it's return value, etc) that was not already kerneldoc'd, I would have
> a dummy spit if I was asked to resubmit with complete documentation.

WFM

> I'm thinking that someone with  Super Saiyan levels of script-fu could
> probably automate the addition of kerneldoc stubs with 'undocumented'
> text

I wonder ... you still need to reference the files in the templates anyway.

> I really don't mind what the documentation rules are, but the MUST be
> on the wiki. One this note, I think we should merge the 'Coding Style'
> and  'Patches' pages of the wiki and rename them to something more
> obvious like, for example, 'Rules for submitting U-Boot patches'.
> Also, I think a regular reminder (say every two weeks) on the mailing
> list pointing out the 'developer rules' on the wiki would be good - we
> tend to get quite a number of on-off patches from new developers that
> don't meet the submission criteria simply because they a blissfully
> ignorant of them.

+1

> Slightly OT - what is happening with the proposed patch tracker?

no :-C

> Regards,
> 
> Graeme

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Scott Wood]

On 09/26/2012 10:26:55 AM, Marek Vasut wrote:
> Dear Wolfgang Denk,
> 
> > Dear Marek,
> > - 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.

-1

The project you're copying from doesn't make it mandatory.  Why should  
U-Boot?  What would it be mandatory for?  Major public APIs?   
Semi-private functions shared between a few related files?  Every  
little static function?

We already have too many arbitrary rules with inconsistent  
enforcement.  What's wrong with just encouraging it where appropriate,  
and insisting only if the maintainer deems it important enough in  
context?

OTOH, I don't think patches should be rejected for having that extra  
asterisk, regardless of whether we encourage kerneldoc in U-Boot  
(unless we adopt a different tool with different requirements).   
Kerneldoc-style headers are still useful documentation even if we don't  
use the actual kerneldoc tool, code can be shared between Linux and  
U-Boot, people can maintain their existing Linux habits, etc.  It's a  
weak argument to point to the CodingStyle document as forbidding it  
when it's clear that the project that CodingStyle comes from uses this  
all over the place.

> >   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 then someone's going to complain that the commenting should be a  
separate patch... more red tape. :-P

-Scott

[U-Boot] KernelDoc

[Marek Vasut]

Dear Scott Wood,

> On 09/26/2012 10:26:55 AM, Marek Vasut wrote:
> > Dear Wolfgang Denk,
> > 
> > > Dear Marek,
> > > - 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.
> 
> -1
> 
> The project you're copying from doesn't make it mandatory.

Ok, you overvoted me here completely. My point was so that in order to have 
really useful documentation, we should make sure people don't slack on creating 
it.

> Why should
> U-Boot?  What would it be mandatory for?  Major public APIs?
> Semi-private functions shared between a few related files?  Every
> little static function?

I believe everything shall eventually be documented. If it is not to be 
enforced, ok.

> We already have too many arbitrary rules with inconsistent
> enforcement.

True. We need to make a proper list of these rules.

> What's wrong with just encouraging it where appropriate,
> and insisting only if the maintainer deems it important enough in
> context?
> 
> OTOH, I don't think patches should be rejected for having that extra
> asterisk, regardless of whether we encourage kerneldoc in U-Boot
> (unless we adopt a different tool with different requirements).
> Kerneldoc-style headers are still useful documentation even if we don't
> use the actual kerneldoc tool, code can be shared between Linux and
> U-Boot, people can maintain their existing Linux habits, etc.  It's a
> weak argument to point to the CodingStyle document as forbidding it
> when it's clear that the project that CodingStyle comes from uses this
> all over the place.
> 
> > >   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 then someone's going to complain that the commenting should be a
> separate patch... more red tape. :-P

:-D

> -Scott

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Tom Rini]

On Tue, Sep 25, 2012 at 10:46:10PM +0200, Marek Vasut wrote:

> Hi all!
> 
> 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?

The biggest problem I see with re-using kernel-style doc is that for the
subsytems we sync with the kernel we've probably got incorrect
documentation due to what we stub out and so forth.  That said, we can
somewhat deal with this when we add the tmpl file that makes the actual
output.

I think the first and most important step is to document the code that
comes in and isn't trivial.  If DM is going to do kernel-doc style
comments, good.  But we need to borrow the Documentation/DocBook
Makefile and logic and so on from the kernel first.  And add template
files for the DM sections so something can be spit out.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20120926/ea1bac65/attachment.pgp>

[U-Boot] KernelDoc

[Marek Vasut]

Dear Tom Rini,

> On Tue, Sep 25, 2012 at 10:46:10PM +0200, Marek Vasut wrote:
> > Hi all!
> > 
> > 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?
> 
> The biggest problem I see with re-using kernel-style doc is that for the
> subsytems we sync with the kernel we've probably got incorrect
> documentation due to what we stub out and so forth.

+1, but then the creator of the patch is responsible for keeping the docs 
inline.

> That said, we can
> somewhat deal with this when we add the tmpl file that makes the actual
> output.

Uh, can you elaborate please?

> I think the first and most important step is to document the code that
> comes in and isn't trivial.

+1

> If DM is going to do kernel-doc style
> comments, good.

Not only DM please.

> But we need to borrow the Documentation/DocBook
> Makefile and logic and so on from the kernel first.  And add template
> files for the DM sections so something can be spit out.

I'd leave that for step 2 (documentation generation) and don't bother with this 
right away.

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek,

In message <201209262110.18172.marex@denx.de> you wrote:
> 
> > But we need to borrow the Documentation/DocBook
> > Makefile and logic and so on from the kernel first.  And add template
> > files for the DM sections so something can be spit out.
> 
> I'd leave that for step 2 (documentation generation) and don't bother with this 
> right away.

If you don't build documentation right from the beginning, you will
not notice any errors or deficiencies in the comments, and reworking
later will be way more effort.

I think if we add it, then it needs to be done Right (TM).

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
"Ja, mach' nur einen Plan,    sei nur ein grosses Licht
und mach' dann noch 'nen zweiten Plan,    geh'n tun sie beide nicht."
                                     -- Bert Brecht, Dreigroschenoper

[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek,
> 
> In message <201209262110.18172.marex@denx.de> you wrote:
> > > But we need to borrow the Documentation/DocBook
> > > Makefile and logic and so on from the kernel first.  And add template
> > > files for the DM sections so something can be spit out.
> > 
> > I'd leave that for step 2 (documentation generation) and don't bother
> > with this right away.
> 
> If you don't build documentation right from the beginning, you will
> not notice any errors or deficiencies in the comments, and reworking
> later will be way more effort.

I agree with this, but I can not do that right now. I'm flat out too swamped.

> I think if we add it, then it needs to be done Right (TM).

I agree

OT: I would hate to rework the patches that already follow that style and then 
rework them again. Maybe we can do a compromise, drop the initial double-
asterisk and otherwise follow the kernel-doc?

> Best regards,
> 
> Wolfgang Denk

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek,

In message <201209262154.59207.marex@denx.de> you wrote:
>
> OT: I would hate to rework the patches that already follow that style and then 
> rework them again. Maybe we can do a compromise, drop the initial double-
> asterisk and otherwise follow the kernel-doc?

That is always possible, of course.

But I recommend just to wait a few days.  The MW isn't open anyway
yet, and maybe there will be some agreement on kernel-doc.  I smell a
wumpus.

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
I program, therefore I am.

[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek,
> 
> In message <201209262154.59207.marex@denx.de> you wrote:
> > OT: I would hate to rework the patches that already follow that style and
> > then rework them again. Maybe we can do a compromise, drop the initial
> > double- asterisk and otherwise follow the kernel-doc?
> 
> That is always possible, of course.
> 
> But I recommend just to wait a few days.  The MW isn't open anyway
> yet, and maybe there will be some agreement on kernel-doc.  I smell a
> wumpus.

Agreement would be really nice, I just don't have the capacity to do the support 
infrastructure.

> Best regards,
> 
> Wolfgang Denk

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Tom Rini]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 09/26/12 12:10, Marek Vasut wrote:
> Dear Tom Rini,
> 
>> On Tue, Sep 25, 2012 at 10:46:10PM +0200, Marek Vasut wrote:
>>> Hi all!
>>> 
>>> 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?
>> 
>> The biggest problem I see with re-using kernel-style doc is that
>> for the subsytems we sync with the kernel we've probably got
>> incorrect documentation due to what we stub out and so forth.
> 
> +1, but then the creator of the patch is responsible for keeping
> the docs inline.

Which will in turn make a mess for further re-syncs.  This should
probably just be dealt with in the tmpl file for whatever reads the
drivers/mtd/nand files.

>> That said, we can somewhat deal with this when we add the tmpl
>> file that makes the actual output.
> 
> Uh, can you elaborate please?

How familiar with kerneldoc are you?  Yes, you put specially formatted
comments into source files.  But you also write a tmpl file (see
Documentation/DocBook/kgdb.tmpl for example) that references the code
and further elaborates on things and so on.

>> I think the first and most important step is to document the code
>> that comes in and isn't trivial.
> 
> +1
> 
>> If DM is going to do kernel-doc style comments, good.
> 
> Not only DM please.

Yes, I'm just using this as an example.

>> But we need to borrow the Documentation/DocBook Makefile and
>> logic and so on from the kernel first.  And add template files
>> for the DM sections so something can be spit out.
> 
> I'd leave that for step 2 (documentation generation) and don't
> bother with this right away.

No.  In order for everyone who isn't on your team to understand what
you're doing, documentation is needed.  And I know you already agree
here.  What I'm saying is that instead of for example a static
doc/driver-model/UDM-serial.txt we would move to having
doc/DocBook/UDM-serial.tmpl which would cover the same content as the
current file, reference the code in question and if A and B get out of
sync, well, this is something you and your team should check before
posting.  Making sure you document what you code AND code what you
document is important.

- -- 
Tom
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://www.enigmail.net/

iQIbBAEBAgAGBQJQY15CAAoJENk4IS6UOR1WrsYP90xS8QZg94tOEAwZ+RsCDZMC
2/eiFDwFo9UySK+5FnzKl2uARfLTje0Dn46cUleKgaEpO9yFx72g5V83/uZt/wrF
J9IYp4Mp4W3RLvBpX+Rl59lT7ZxDzI6798KM7ydT+UCQ99nTY9qhfQ8ZWy7SN2ho
KnJYJ1gRPBegK95eVEeOlq5GTg6DMJ28ln1P4xFvxRzuwJ6zTZu+bwMiFrHyyEbD
0RxubSuyk+puVEOlGxiwR33Sgc/lTX0H960tuZoIUrHXPp5jL6BZnDx6MFIYPNAz
r5200q32qXeAtWD31oYWDmDqFb8Ftzenx4yYPfNFk/sJ4fhCVFaetoRc/RXQQi4o
fx3h4xQYzJd/n7IydSHJqyp8EMj+FI3Eaqp/2HPOJggV81Hls73fVGGrWIa1Q+ue
tddQOXjrqRAbqyzAeQo9tQYiheeV7GZi2YQ7pIh9y6Ta+R/epLfBbEoX2Jik/FuK
EHDNoxvhPC0D+Z7uTXmoX9POaSbYRKfLnzXde6Q9Od/6MkIwd6TuF1SyDo/fNtix
+cGfvvHog0KkepqH0QdGb5n1w7YFaavbfdKDa3j3lvYST70kI+r+ljEBq37QG8GE
sSNUOiOlz9xtUpx8BorX4TvrH5xlfJNPE1IrOVH0BZ1xpLU4LoMjO6LlMsP4xIId
UDNJ8cIXHmePaME6hXE=
=Yf9e
-----END PGP SIGNATURE-----

[U-Boot] KernelDoc

[Marek Vasut]

Dear Tom Rini,

> On 09/26/12 12:10, Marek Vasut wrote:
> > Dear Tom Rini,
> > 
> >> On Tue, Sep 25, 2012 at 10:46:10PM +0200, Marek Vasut wrote:
> >>> Hi all!
> >>> 
> >>> 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?
> >> 
> >> The biggest problem I see with re-using kernel-style doc is that
> >> for the subsytems we sync with the kernel we've probably got
> >> incorrect documentation due to what we stub out and so forth.
> > 
> > +1, but then the creator of the patch is responsible for keeping
> > the docs inline.
> 
> Which will in turn make a mess for further re-syncs.  This should
> probably just be dealt with in the tmpl file for whatever reads the
> drivers/mtd/nand files.
> 
> >> That said, we can somewhat deal with this when we add the tmpl
> >> file that makes the actual output.
> > 
> > Uh, can you elaborate please?
> 
> How familiar with kerneldoc are you?  Yes, you put specially formatted
> comments into source files.  But you also write a tmpl file (see
> Documentation/DocBook/kgdb.tmpl for example) that references the code
> and further elaborates on things and so on.
> 
> >> I think the first and most important step is to document the code
> >> that comes in and isn't trivial.
> > 
> > +1
> > 
> >> If DM is going to do kernel-doc style comments, good.
> > 
> > Not only DM please.
> 
> Yes, I'm just using this as an example.
> 
> >> But we need to borrow the Documentation/DocBook Makefile and
> >> logic and so on from the kernel first.  And add template files
> >> for the DM sections so something can be spit out.
> > 
> > I'd leave that for step 2 (documentation generation) and don't
> > bother with this right away.
> 
> No.  In order for everyone who isn't on your team to understand what
> you're doing, documentation is needed.  And I know you already agree
> here.  What I'm saying is that instead of for example a static
> doc/driver-model/UDM-serial.txt we would move to having
> doc/DocBook/UDM-serial.tmpl which would cover the same content as the
> current file, reference the code in question and if A and B get out of
> sync, well, this is something you and your team should check before
> posting.  Making sure you document what you code AND code what you
> document is important.

Yes, I agree. We will need a code documentation anyway, so I might as well 
invest time into this.

Best regards,
Marek Vasut

[U-Boot] KernelDoc

[Marek Vasut]

Dear Marek Vasut,

> Hi all!
> 
> 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?
> 
> See [1] in Linux kernel tree for what I mean.
> 
> [1] Documentation/kernel-doc-nano-HOWTO.txt

So I've been hacking on it for a bit, see the first stab at [1]. As for the 
ruleset, I propose this addition for the Wiki [2]:

-->8--

U-Boot code documentation
=========================

U-Boot adopted the kernel-doc annotation style, this is the only exception from 
multi-line comment rule of Coding Style. While not mandatory, adding 
documentation is strongly advised. The Linux kernel kernel-doc document [3] 
appliest with no changes.

--8<--

[1] http://twilight.ponies.cz/kerneldoc/
[2] http://www.denx.de/wiki/U-Boot/CodingStyle
[3] 
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/kernel-
doc-nano-HOWTO.txt

Best regards,
Marek Vasut