For example, the URL points to a section of and eclass example which has the following: # domacosapp: install a macos .app file. Usage is 'domacosapp file' or # 'domacosapp file newfile'. domacosapp() { ... This I think should be: # @FUNCTION: domacosapp # @USAGE: file [newfile] # @DESCRIPTION: Install a macos.app file. It would also be nice if it could mention which @<TAG>s are allowed where. I.e., I noticed that @EXAMPLE for a @FUNCTION doesn't get outputted into the eclass's manpage by app-portage/eclass-manpages-20100821 so it appears not to be allowed for functions but to be allowed for the eclass's header's docs. (I hope I filed this bug at the right place...)
Created attachment 436186 [details, diff] 0001-eclass-writing-add-Documenting-Eclasses-section-and-.patch
Created attachment 436188 [details, diff] 0002-eclass-writing-add-documentation-to-the-first-existi.patch
Created attachment 436190 [details, diff] 0003-eclass-writing-add-documentation-to-the-incorrect-us.patch
Created attachment 436192 [details, diff] 0004-eclass-writing-add-documentation-to-the-build-system.patch
I added a section about the documentation format, gave examples of the correct headers, and then went back and fixed all of the existing examples.
Created attachment 451901 [details, diff] Improve the text with tables Here's the take two in enhancing the text with tables: http://dev.gentoo.org/~gokturk/devmanual/bug373145/eclass-writing/index.html
(In reply to Göktürk Yüksek from comment #6) > Created attachment 451901 [details, diff] [details, diff] > Improve the text with tables > > Here's the take two in enhancing the text with tables: > http://dev.gentoo.org/~gokturk/devmanual/bug373145/eclass-writing/index.html Thanks again for your work on this. I really like the overall layout. I have a few nitpicky suggestions, but feel free at any point to commit what you have and tell me to send a patch for the additional stuff. 1. Documenting Eclasses a. Instead of"empty new lines", I would call them "blank lines". b. Pick one of "elements" or "entities" and stick with it. c. The @CODE part is too hard to understand, but see #2 below. 2. Add an example for the @CODE tag. Once there's an example (and I can see how to use it), I might be able to come up with a better description for the "Documenting Eclasses" paragraph. 3. Since we're recommending that eclasses die in EAPIs that they don't support, it would be helpful to add such a check at the beginning of the existing example eclasses. People copy/paste examples more readily than they read the manual. 4. Some "which"es could be "that"s. I know this is pedantic, so I'll quote someone else (Knuth, Mathematical Writing): Which brings us to our next issue: Are whiches that could be thats always wrong? Don [Knuth] said that now that he knows the rules, he finds every "wicked which" an irritating distraction from his reading enjoyment. He seemed to imply that whiches in restrictive clauses are always wrong. Basically, if you can change "which" to "that", then do it -- it will sound better. 5. An example with more than one author would help clarify how they go on separate lines. 6. The concept of "return value" in bash is a little murky... I suspect that @RETURN should also document any output from the function, but we can deal with this some other time. 7. Add examples of @ECLASS-VARIABLE and @VARIABLE. What you have is already a huge improvement, so I don't want to hold this up forever trying to make it perfect. It's OK to commit something 90% there (but still an improvement) and then fix it up afterwards. I can send patches for most of the above if you like.
(In reply to Michael Orlitzky from comment #7) > (In reply to Göktürk Yüksek from comment #6) > > Created attachment 451901 [details, diff] [details, diff] [details, diff] > > Improve the text with tables > > > > Here's the take two in enhancing the text with tables: > > http://dev.gentoo.org/~gokturk/devmanual/bug373145/eclass-writing/index.html > > Thanks again for your work on this. I really like the overall layout. I have > a few nitpicky suggestions, but feel free at any point to commit what you > have and tell me to send a patch for the additional stuff. > > 1. Documenting Eclasses > > a. Instead of"empty new lines", I would call them "blank lines". Done. > b. Pick one of "elements" or "entities" and stick with it. Elements sounded better. > c. The @CODE part is too hard to understand, but see #2 below. I left this as is for now though I agree with the assessment. > > > 2. Add an example for the @CODE tag. Once there's an example (and I can see > how to use it), I might be able to come up with a better description for the > "Documenting Eclasses" paragraph. > > 3. Since we're recommending that eclasses die in EAPIs that they don't > support, it would be helpful to add such a check at the beginning of the > existing example eclasses. People copy/paste examples more readily than they > read the manual. > It could also help with people treating EAPIs as integers. > 4. Some "which"es could be "that"s. I know this is pedantic, so I'll quote > someone else (Knuth, Mathematical Writing): > > Which brings us to our next issue: Are whiches that could be thats always > wrong? Don [Knuth] said that now that he knows the rules, he finds every > "wicked which" an irritating distraction from his reading enjoyment. He > seemed to imply that whiches in restrictive clauses are always wrong. > > Basically, if you can change "which" to "that", then do it -- it will sound > better. > Some of the whiches have been eliminated. > 5. An example with more than one author would help clarify how they go on > separate lines. > > 6. The concept of "return value" in bash is a little murky... I suspect that > @RETURN should also document any output from the function, but we can deal > with this some other time. > I think if there's no return value, the output can be explained in @DESCRIPTION instead. > 7. Add examples of @ECLASS-VARIABLE and @VARIABLE. > > > What you have is already a huge improvement, so I don't want to hold this up > forever trying to make it perfect. It's OK to commit something 90% there > (but still an improvement) and then fix it up afterwards. I can send patches > for most of the above if you like. Merged in https://github.com/gentoo/devmanual.gentoo.org/compare/092cc15...9623823 We still need to add the enhancements we speak of.
(In reply to Göktürk Yüksek from comment #8) > Merged in > https://github.com/gentoo/devmanual.gentoo.org/compare/092cc15...9623823 > We still need to add the enhancements we speak of. Are you going to follow up on this, or can this bug be closed?
Based on my re-reading of the bug, here are the missing enhancements: 2. Add an example for the @CODE tag. Once there's an example (and I can see how to use it), I might be able to come up with a better description for the "Documenting Eclasses" paragraph. 3. Since we're recommending that eclasses die in EAPIs that they don't support, it would be helpful to add such a check at the beginning of the existing example eclasses. People copy/paste examples more readily than they read the manual. (although somewhat addressed by 4ada72fc43918e1d8d652deb9e5f0d1e060a36ef) 5. An example with more than one author would help clarify how they go on separate lines. 7. Add examples of @ECLASS-VARIABLE and @VARIABLE. I also see that the examples need a large overhaul (they still have "$Id$" in the header). I think this bug is still relevant and worth keeping open. I have no time frame for fixing it though.
(In reply to Göktürk Yüksek from comment #10) > Based on my re-reading of the bug, here are the missing enhancements: I think it would be helpful to split these into separate bugs, so that they can individually be fixed by someone with a few hours but not a whole week of free time.
FWIW, I did somewhat start to address this (the examples not so much) a while ago, as did ulm: commit cd392d0c6cd064ac3a1381111e678f4fe111afcc Author: Ulrich Müller <ulm@gentoo.org> Date: Thu Sep 2 17:36:26 2021 +0200 eclass-writing: @DEAD must be the first tag Signed-off-by: Ulrich Müller <ulm@gentoo.org> commit b691f696abfbc33a4e3f3bea2100ebc466c24e6b Author: Ulrich Müller <ulm@gentoo.org> Date: Thu Sep 2 09:54:21 2021 +0200 eclass-writing: More documentation tags @SUBSECTION, @SUPPORTED_EAPIS, @PROVIDES, and @DEPRECATED. Signed-off-by: Ulrich Müller <ulm@gentoo.org> commit 336d16aa5fe8c564a15760659e1670a0e98e58b3 Author: Sam James <sam@gentoo.org> Date: Mon Mar 22 06:56:29 2021 +0000 eclass-writing: add new eclass doc tags for Eclass Function Variables Adds: * @USER_VARIABLE * @INCLUDES_EPREFIX * @DEPRECATED Signed-off-by: Sam James <sam@gentoo.org> Signed-off-by: Ulrich Müller <ulm@gentoo.org> commit b80285bdc37a51a2628bf4b7edd44717c15062cb Author: Sam James <sam@gentoo.org> Date: Mon Mar 22 06:44:06 2021 +0000 eclass-writing: add new eclass doc tags for Eclass Functions Adds: * @INCLUDES_EPREFIX * @DEPRECATED Signed-off-by: Sam James <sam@gentoo.org> Signed-off-by: Ulrich Müller <ulm@gentoo.org> commit 3d47a2bc63aec2ac36b63eae6b84905487f6ddd6 Author: Sam James <sam@gentoo.org> Date: Mon Mar 22 06:37:51 2021 +0000 eclass-writing: add new eclass doc tags for Eclass Variables Adds: * @PRE_INHERIT * @USER_VARIABLE * @OUTPUT_VARIABLE * @INCLUDES_EPREFIX * @DEPRECATED Signed-off-by: Sam James <sam@gentoo.org> Signed-off-by: Ulrich Müller <ulm@gentoo.org> ... but the rest of the points here seem to remain. I agree with mjo that separate bugs should exist for those suggestions.
