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
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@lists.denx.de http://lists.denx.de/mailman/listinfo/u-boot
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
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@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.
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
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
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
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.
- 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
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
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
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
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
-----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
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
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
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
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
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=Do... doc-nano-HOWTO.txt
Best regards,
Wolfgang Denk
Best regards, Marek Vasut
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=Do... doc-nano-HOWTO.txt
Make it so.
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
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
-----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
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
-----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
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
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
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
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
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
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.
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
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
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
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
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
-----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
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
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=Do... doc-nano-HOWTO.txt
Best regards, Marek Vasut
participants (9)
-
Fabio Estevam -
Graeme Russ -
Joe Hershberger -
Marek Vasut -
Prabhakar Lad -
Scott Wood -
Stefan Roese -
Tom Rini -
Wolfgang Denk