Re: [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification

[Markus Heiser]

Hi Randy,

thanks for your amendments / has been fixed [1]

[1] https://github.com/return42/linux/commit/98a9fc42cbd0c23b266ac28494dafe20d7920d05

Am 09.06.2016 um 20:05 schrieb Randy Dunlap <rdunlap@xxxxxxxxxxxxx>:

> Hi,
> 
> Some spellos and a few questions...

>> + b/Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst
>> +Within the *vintage* kernel-doc mode the kernel-doc parser highlights the pattern
>> +above, but he also dogged ignores any whitespace formatting/markup.
> 
> what is "dogged"??
> 

... "insistently" ...  

>> +Within reST markup (the new bas format), the wildcard in the string
> 
> what is "bas"??
> 

sorry, another typo: "the new base format"

> 
>> +``drm_get_*_name`` has to be masked: ``drm_get_\\*_name``. Some more examples
>> +from reST markup:
>> +
>> +* Emphasis "*":  like ``*emphasis*`` or ``**emphasis strong**``
>> +* Leading "_" :  is a *anchor* in reST markup (``_foo``).
>> +* Trailing "_:  is a reference in reST markup (``foo_``).
>> +* interpreted text: "`"
>> +* inline literals: "``"
>> +* substitution references: "|"
>> +
>> +As long as you in the *vintage* kernel-doc mode, these special strings will be
>> +masked in the reST output and can't be used as *plain-text markup*.
>> +
>> +
>> 
> 
> My only "requirement" (if I may have one) is that we not introduce big
> hurdles to kernel developers adding documentation.
> 
> I'm not saying that this is a big hurdle.. I haven't looked at it enough
> yet.

The parser has two modes, *vintage* "kernel-doc" and "reST". You can
switch between these modes in the source code with this two comments:  

   /* parse-markup: reST */
   /* parse-markup: kernel-doc */

Jani says that we should prefer reST as the default mode for parsing, I 
recommended kernel-doc as default, because all old source are written
with the *vintage* markup .. the odd side of this is, that you have to put
a /* parse-markup: reST */ at the top of your source file to get reST
in use ... I don't know what the best choice might bee ... I think, it
is the best to make an option in the conf.py for this.

-- Markus--


> 
> -- 
> ~Randy