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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:	Fri, 10 Jun 2016 18:00:17 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Randy Dunlap <rdunlap@...radead.org>
Cc:	corbet@....net, jani.nikula@...el.com, daniel.vetter@...ll.ch,
	grant.likely@...retlab.ca, mchehab@....samsung.com,
	keithp@...thp.com, linux-kernel@...r.kernel.org,
	linux-doc@...r.kernel.org, hverkuil@...all.nl
Subject: Re: [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification

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@...radead.org>:

> 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