On 02/13/2018 12:59 PM, Jonathan Corbet wrote:
> On Thu, 8 Feb 2018 06:45:07 -0800
> Matthew Wilcox <willy@xxxxxxxxxxxxx> 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...
--
~Randy
--
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
