Em Thu, 10 May 2018 14:20:36 +0200
Peter Zijlstra [off-list ref] escreveu:

On Thu, May 10, 2018 at 06:38:05AM -0300, Mauro Carvalho Chehab wrote:

quoted

Em Thu, 10 May 2018 01:38:38 -0700
Christoph Hellwig [off-list ref] escreveu:
  

quoted

quoted

  * 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.

quoted

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.

quoted

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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html