On Tue, Feb 13, 2018 at 01:03:18PM -0800, Randy Dunlap wrote: > On 02/13/2018 12:59 PM, Jonathan Corbet wrote: > > I think this makes sense to do, but I really would like to see an intro > > comment on the split-man.pl script itself. Somebody wandering through > > the scripts directory should be able to look at the top of the file and > > know what the script does without having to reverse-engineer delightful > > stuff like: > > > >> if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { Fixed in v2 ;-) > >> Fix whitespace in example > >> Restructure kernel-doc.rst > >> Add a Style Guide section > > > > This last one worries me a bit because we're starting to impinge a bit on > > the coding style document. If we're going to give guidance on things > > like parameter names, I think that coding-style.rst is the right place > > for it. Dropped for v2. > As long as the examples don't dictate style... > E.g., Matthew likes to use: > > + * @gfp: Memory allocation flags. > > a. Capitalize the first word after @param: > b. end with a period (even though it's not a sentence) > > I disagree with both of those. OK, so which do you think looks better: https://www.kernel.org/doc/html/latest/core-api/idr.html#c.idr_get_cursor https://www.kernel.org/doc/html/latest/core-api/idr.html#c.idr_alloc_u32 (yes, I have failed to be consistent. I shall apply appropriate amounts of self-flagellation and fix them shortly.) -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html