KernelDoc
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,
Quoted 11 lines · 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?
+1 for kerneldoc.
Regards,
--Prabhakar Lad
Quoted 12 lines
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.txtBest regards,
Marek Vasut
_______________________________________________
U-Boot mailing list
U-Boot at lists.denx.de
http://lists.denx.de/mailman/listinfo/u-boot
Dear Prabhakar Lad,
Quoted 7 lines · In message <CA+V-a8vZ-715eL1MNvxhYCGNWv5YSGuoNn5hZQeMFN5ZKtpKMQ@mail.gmail.com>…
Quoted 6 lines
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
Signature · 5 lines
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.
Hi Wolfgang,
Quoted 4 lines · Wolfgang Denk
Dear Prabhakar Lad,
Quoted 1 line · In message <CA+V-a8vZ-715eL1MNvxhYCGNWv5YSGuoNn5hZQeMFN5ZKtpKMQ@mail.gmail.com>…
Quoted 9 lines
Quoted 6 lines
Quoted 5 lines
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
Quoted 4 lines
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).
Quoted 2 lines
What is the goal you see for using this?
Readability of the code will increase.
Regards,
--Prabhakar Lad
Quoted 13 lines
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.
Dear Prabhakar Lad,
Quoted 4 lines · In message <CA+V-a8ujwAdpKKtm+7GsC7DRB5DtCFUhE+7Jn69sBVj5kz+1Dg@mail.gmail.com>…
Quoted 3 lines
Could you please explain what exactly your vote is supposed to mean?
My vote was for using kerneldoc to annotate functions and generate documentation
...
Quoted 1 line
Readability of the code will increase.
Which sort of documentation would you want to generate?
Best regards,
Wolfgang Denk
Signature · 5 lines
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
Dear Marek,
Quoted 11 lines · In message <[email protected]> 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
Signature · 5 lines
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_
Dear Wolfgang Denk,
Quoted 15 lines
Dear Marek,
Quoted 11 lines · In message <[email protected]> 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?
Quoted 7 lines
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
Quoted 2 lines
- 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.
Quoted 7 lines
- 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).
Quoted 2 lines
- 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.
Quoted 1 line
- If so, what does that mean for patches that touch existing code?
Ask the current custodian to annotate their code.
Quoted 2 lines
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.
Quoted 1 line
If I change the calling interface, must I add documentation then?
Of course, yes.
Quoted 1 line
- 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.
Quoted 3 lines
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 :-)
Quoted 1 line
- 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.
Quoted 3 lines
For
making sure it gives a usable result, it looks more or less consistent?
Reviewer. The documentation generation shall be postponed.
Quoted 5 lines
- What about internationalization? Who will do the translations? ;-)
Best regards,
Wolfgang Denk
Best regards,
Marek Vasut
Hi Marek,
Quoted 30 lines · Marek Vasut
Dear Wolfgang Denk,
Quoted 15 lines
Dear Marek,
Quoted 11 lines · In message <[email protected]> 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?
Quoted 7 lines
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
Quoted 2 lines
- The first thing we should define is what we want to use it for, i. e. the purpose.
Quoted 7 lines
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.
Quoted 12 lines
Quoted 7 lines
- 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).
Quoted 5 lines
Quoted 2 lines
- 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.
Quoted 3 lines
Quoted 1 line
- 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).
Quoted 5 lines
Quoted 2 lines
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.
Quoted 3 lines
Quoted 1 line
If I change the calling interface, must I add documentation then?
Of course, yes.
Agreed.
[...]
-Joe
Dear Joe Hershberger,
[..]
Quoted 4 lines
Quoted 2 lines
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.
Quoted 4 lines
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
Quoted 7 lines
Quoted 3 lines
Quoted 1 line
- 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 :-(
Quoted 17 lines
Quoted 5 lines
Quoted 2 lines
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.
Quoted 3 lines
Quoted 1 line
If I change the calling interface, must I add documentation then?
Of course, yes.
Agreed.
[...]
-Joe
Dear Marek,
Quoted 10 lines · In message <[email protected]> you wrote:
Quoted 3 lines
- 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.
Quoted 1 line
- 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?
Quoted 9 lines
Quoted 2 lines
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.
Quoted 1 line
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.
Quoted 4 lines
Quoted 1 line
- 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.
Quoted 6 lines
Quoted 3 lines
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?
Quoted 5 lines
Quoted 1 line
- 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
Signature · 5 lines
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
Dear Wolfgang Denk,
Quoted 7 lines
Dear Marek,
Quoted 4 lines · In message <[email protected]> you wrote:
Quoted 3 lines
- Will we make this mandatory? So that we will reject all new code
that is not documented according to kernel-doc rules?
Quoted 8 lines
Quoted 6 lines
Yes please, make it mandatory. Otherwise people won't obey and the documentation will suffer ... and all this would be meaningless.
Quoted 1 line
- 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 ;-)
Quoted 1 line
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.
Quoted 2 lines
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.
Quoted 8 lines
Quoted 8 lines
Quoted 2 lines
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.
Quoted 1 line
If I change the calling interface, must I add documentation then?
Quoted 7 lines
Quoted 1 line
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.
Quoted 12 lines
Quoted 4 lines
Quoted 1 line
- 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.
Quoted 5 lines
Quoted 4 lines
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?
Quoted 6 lines
Quoted 3 lines
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.
Quoted 8 lines
Quoted 5 lines
Quoted 1 line
- 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.
Quoted 3 lines
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.
Quoted 3 lines
Best regards,
Wolfgang Denk
Best regards,
Marek Vasut
Dear Marek,
Quoted 5 lines · In message <[email protected]> you wrote:
Quoted 3 lines
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.
Quoted 8 lines
Quoted 5 lines
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.
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines
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...
Quoted 4 lines
Quoted 2 lines
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.
Quoted 5 lines
Quoted 3 lines
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
Signature · 4 lines
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"
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 09/26/12 13:57, Wolfgang Denk wrote:
[snip]
Quoted 7 lines
Quoted 5 lines
Quoted 3 lines
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-----
Dear Wolfgang Denk,
Quoted 8 lines
Dear Marek,
Quoted 4 lines · In message <[email protected]> you wrote:
Quoted 2 lines
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.
Quoted 7 lines
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!
Quoted 10 lines
Quoted 8 lines
Quoted 5 lines
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.
Quoted 3 lines
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.
Quoted 9 lines
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines
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
Quoted 7 lines
Quoted 4 lines
Quoted 2 lines
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
Quoted 7 lines
Quoted 5 lines
Quoted 3 lines
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.
Quoted 3 lines
Best regards,
Wolfgang Denk
Best regards,
Marek Vasut
Dear Marek Vasut,
Quoted 6 lines · In message <[email protected]> you wrote:
Quoted 4 lines
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
Signature · 10 lines
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"
Dear Wolfgang Denk,
Quoted 9 lines
Dear Marek Vasut,
Quoted 5 lines · In message <[email protected]> you wrote:
Quoted 3 lines
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.
Quoted 7 lines
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?
Quoted 3 lines
Best regards,
Wolfgang Denk
Best regards,
Marek Vasut
Dear Marek Vasut,
Quoted 2 lines · In message <[email protected]> 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
Signature · 5 lines
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
Dear Wolfgang Denk,
Quoted 7 lines
Dear Marek Vasut,
Quoted 2 lines · In message <[email protected]> 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
Quoted 3 lines
Best regards,
Wolfgang Denk
Best regards,
Marek Vasut
Quoted 25 lines · Marek Vasut
Dear Wolfgang Denk,
Quoted 7 lines
Dear Marek Vasut,
Quoted 2 lines · In message <[email protected]> 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.
Quoted 7 lines
--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.
Signature · 8 lines
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>
Dear Tom Rini,
Quoted 28 lines · Marek Vasut
Quoted 27 lines
Dear Wolfgang Denk,
Quoted 7 lines
Dear Marek Vasut,
Quoted 2 lines · In message <[email protected]> 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<--
Quoted 7 lines
Quoted 5 lines
[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.txtMake it so.
Let's wait for Wolfgang, I'd like to have his ACK on this please.
Best regards,
Marek Vasut
Dear Tom Rini,
Quoted 28 lines · Marek Vasut
Quoted 27 lines
Dear Wolfgang Denk,
Quoted 7 lines
Dear Marek Vasut,
Quoted 2 lines · In message <[email protected]> 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<--
Quoted 7 lines
Quoted 5 lines
[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.txtMake it so.
As -next will be merged into master tomorrow or so, done.
Best regards,
Marek Vasut
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Quoted 3 lines · Wolfgang Denk
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-----
On 09/26/2012 09:54 PM, Wolfgang Denk wrote:
<snip>
Quoted 9 lines
Quoted 3 lines
Quoted 1 line
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>
Quoted 8 lines
Quoted 5 lines
Quoted 1 line
- 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]
Quoted 5 lines
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-----
Quoted 10 lines · Stefan Roese
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,
Quoted 5 lines
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
Quoted 5 lines
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
Quoted 6 lines
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
Quoted 3 lines
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.
Quoted 9 lines
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
Quoted 1 line
Slightly OT - what is happening with the proposed patch tracker?
no :-C
Quoted 3 lines
Regards,
Graeme
Best regards,
Marek Vasut
Quoted 9 lines · Marek Vasut
Dear Wolfgang Denk,
Quoted 3 lines
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.
Quoted 7 lines
Quoted 1 line
If I change the major part of an existing function (without
changing
Quoted 1 line
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,
Quoted 8 lines · Marek Vasut
Quoted 7 lines
Dear Wolfgang Denk,
Quoted 4 lines
Dear Marek,
- Will we make this mandatory? So that we will reject all new codethat is not documented according to kernel-doc rules?
Quoted 7 lines
Quoted 3 lines
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.
Quoted 4 lines
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.
Quoted 2 lines
We already have too many arbitrary rules with inconsistent enforcement.
True. We need to make a proper list of these rules.
Quoted 18 lines
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.
Quoted 4 lines
Quoted 1 line
If I change the major part of an existing function (without
changing
Quoted 8 lines
Quoted 5 lines
Quoted 1 line
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
Quoted 1 line
-Scott
Best regards,
Marek Vasut
Quoted 6 lines · 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.
Quoted 7 lines
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.
Signature · 8 lines
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>
Dear Tom Rini,
Quoted 12 lines · Marek Vasut
Quoted 11 lines
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?
Quoted 6 lines
Quoted 2 lines
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.
Quoted 3 lines
That said, we can
somewhat deal with this when we add the tmpl file that makes the actual output.
Uh, can you elaborate please?
Quoted 2 lines
I think the first and most important step is to document the code that comes in and isn't trivial.
+1
Quoted 2 lines
If DM is going to do kernel-doc style
comments, good.
Not only DM please.
Quoted 3 lines
But we need to borrow the
Documentation/DocBookMakefileand 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,
Quoted 7 lines · In message <[email protected]> you wrote:
Quoted 4 lines
But we need to borrow the
Documentation/DocBookMakefileand 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
Signature · 6 lines
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, DreigroschenoperDear Wolfgang Denk,
Quoted 7 lines
Dear Marek,
Quoted 4 lines · In message <[email protected]> you wrote:
Quoted 3 lines
But we need to borrow the
Documentation/DocBookMakefileand logic and so on from the kernel first. And add template files for the DM sections so something can be spit out.
Quoted 6 lines
Quoted 2 lines
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.
Quoted 1 line
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?
Quoted 3 lines
Best regards,
Wolfgang Denk
Best regards,
Marek Vasut
Dear Marek,
Quoted 4 lines · In message <[email protected]> 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
Signature · 4 lines
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.
Dear Wolfgang Denk,
Quoted 7 lines
Dear Marek,
Quoted 3 lines · In message <[email protected]> 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?
Quoted 5 lines
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.
Quoted 3 lines
Best regards,
Wolfgang Denk
Best regards,
Marek Vasut
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Quoted 18 lines · Marek Vasut
Dear Tom Rini,
Quoted 16 lines · Marek Vasut
Quoted 14 lines
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?
Quoted 6 lines
Quoted 3 lines
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.
Quoted 4 lines
Quoted 2 lines
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.
Quoted 8 lines
Quoted 2 lines
I think the first and most important step is to document the code that comes in and isn't trivial.
+1
Quoted 1 line
If DM is going to do kernel-doc style comments, good.
Not only DM please.
Yes, I'm just using this as an example.
Quoted 6 lines
Quoted 3 lines
But we need to borrow the
Documentation/DocBookMakefileand 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-----
Dear Tom Rini,
Quoted 58 lines · Marek Vasut
Quoted 18 lines
Dear Tom Rini,
Quoted 16 lines · Marek Vasut
Quoted 14 lines
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?
Quoted 6 lines
Quoted 3 lines
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/nandfiles.Quoted 4 lines
Quoted 2 lines
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.tmplfor example) that references the code and further elaborates on things and so on.Quoted 8 lines
Quoted 2 lines
I think the first and most important step is to document the code that comes in and isn't trivial.
+1
Quoted 1 line
If DM is going to do kernel-doc style comments, good.
Not only DM please.
Yes, I'm just using this as an example.
Quoted 6 lines
Quoted 3 lines
But we need to borrow the
Documentation/DocBookMakefileand 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.
Quoted 9 lines
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.txtwe 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,
Quoted 11 lines
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?
Quoted 6 lines
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