Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Mauro Carvalho Chehab]

Em Thu, 10 May 2018 14:20:36 +0200
Peter Zijlstra <peterz@xxxxxxxxxxxxx> escreveu:

> On Thu, May 10, 2018 at 06:38:05AM -0300, Mauro Carvalho Chehab wrote:
> > Em Thu, 10 May 2018 01:38:38 -0700
> > Christoph Hellwig <hch@xxxxxxxxxxxxx> escreveu:
> >   
> > > >   * Use either while holding wait_queue_head::lock or when used for wakeups
> > > > - * with an extra smp_mb() like:
> > > > + * with an extra smp_mb() like::    
> > > 
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.  
> 
> That is exactly my point; the whole rst stuff detracts from normal text.
> It makes both reading and writing harder than it needs to be.
> 
> > Patches are welcome, although I don't see any easy way to solve it.
> > 
> > In English, the common case is that a line with ends with a colon is
> > followed by a list. E. g.  
> 
> (google) Dictionary says:
> 
> "a punctuation mark (:) used to precede a list of items, a quotation, or
> an expansion or explanation."
> 
> An enumeration (list) is just one of many possible uses of the colon.

True, but the point is that whatever tool is used, it should be able
to uniquely unambiguously identify what it follows.

For example, it if is a list of items, it should keep parsing the
semantics markups inside it e. g. marking %FOO as a constant,
and bar() as a function, etc, following kernel-doc syntax. 

But, if it is a quote, a code example or an ascii artwork, it
should disable all such parsers, enclosing the result into a
literal block.

> > However, in this specific case, it is followed by an ascii artwork. 
> > The double colon is a notation that tells Sphinx to not parse the
> > lines at the next block, placing the contents of it inside a literal
> > block. It is used also when the next lines contain a code example,
> > in order to avoid parsing things like @, () and * inside the code 
> > block.
> > 
> > The kernel-doc tool might eventually have some parsing logic that
> > would replace something to a '::' before sending it to Sphinx.  
> 
> I think typically there will be an 'empty' line between the colon ending
> and the 'example/explanation'. This seems true for a number of comments
> I found in drm using the '::' nonsense.

Unfortunately, that's not true treewide. The presense/absense of a
blank line after a line ending with a colon doesn't indicate if the contents
below should be handled as a literal block or not[1].

[1] you can verify some use cases with:
	$ git grep -A2 "\*.*\s.*:$" -- $(git grep kernel-doc:: Documentation/|cut -d : -f 4-)

> Simple regexes don't do multi-line patterns, but maybe the kerneldoc
> thing can parse it differently.

kernel-doc is a regex-based parser (and not an AI engine). It will do only
what it is programmed for, based on a clear regex-based semantics.

Independently on how easy/hard it would be to use a multi-line pattern
for this, what it is required is a clear non-hint based pattern that
will provide a match for a part of the tag that should be escaped
from normal parsing rules. The m/::$/ is a clear rule.

Do you have a proposal for some other rule? If so, I can see how
feasible is to add it there.

Thanks,
Mauro