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

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]

Message-ID: <20180510073012.5902088e@lwn.net>
Date:   Thu, 10 May 2018 07:30:12 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
Cc:     Christoph Hellwig <hch@...radead.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org, Ingo Molnar <mingo@...hat.com>,
        Peter Zijlstra <peterz@...radead.org>
Subject: Re: [PATCH 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx
 warnings

On Thu, 10 May 2018 06:38:05 -0300
Mauro Carvalho Chehab <mchehab+samsung@...nel.org> wrote:

> (Peter said):
> > 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.  

FWIW, there's no problem with a sentence ending with a single colon.
It's only an issue if you want to flag a special interpretation for the
text that follows that sentence.  Just to be precise.

> Patches are welcome, although I don't see any easy way to solve it.

I could envision some sort of heuristic that would recognize an indented
block containing code.  Probably we could go simpler and force the
"literal block" treatment for any indented block that lacks explicit
enumeration markers.  So:

	this->would_be("a literal block");

but:

  - This would not be

Such a thing would likely be a bit fragile (people feel, rightly, that
they can put anything into normal text) but it might just work well
enough.  For best results, it should probably be done as part of Sphinx
itself, rather than yet another ugly hack in the kerneldoc script.

This particular problem may be solvable, and I'll look into it, but not
right away.  The offline world is being rather insistently obnoxious
these days...

jon