On 02/13/2018 12:59 PM, Jonathan Corbet wrote:
> On Thu,  8 Feb 2018 06:45:07 -0800
> Matthew Wilcox <wi...@infradead.org> wrote:
>> Jon asked me to redo the Context: patch on top of his current docs tree.
>> Unfortunately, I was on a plane at the time, so I started fixing some
>> other small things, and before I knew it, I'd completely restructured
>> the entire doc-guide/kernel-doc.rst file.
>> Feel free to not take it all, particularly the last 'Style Guide' patch.
> OK, this all makes sense.  Mostly.  Here's my quibbles.
>> Matthew Wilcox (6):
>>   Add documentation for Context section
>>   Minor fixes to kernel-doc.rst
>>   Add scripts/split-man.pl
> 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 \"([^\"]*)\"/) {
>>   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.

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.

> I'll go ahead and apply the first five.  I'll try to get around to
> putting a comment on scripts/split-man.pl, but I sure wouldn't mind if
> somebody beat me to it...

To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to