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

Andrea Parri
2018-05-10T12:23:46Z

On Wed, May 09, 2018 at 08:45:18AM -0600, Jonathan Corbet wrote:
> On Wed, 9 May 2018 10:41:20 +0200
> Peter Zijlstra <peterz@infradead.org> wrote:
>
> > > This is easily done by using "::" instead of just ":".
> >
> > And I'll voice my objection once again. This makes a regular comment
> > worse. This rst stuff is utter shit for making normal text files less
> > readable in your favourite text editor.
> >
> > If this gets merged, I'll simply remove that spurious ':' the next time
> > I'm near that comment.
>
> Seriously, Peter?
>
> It's a simple colon. It goes along with the /** marker for kerneldoc
> comments and the @ markers found within them, both of which you seem to
> have found a way to live with.
>
> The RST work was discussed for a year before we even started. It has
> brought in the efforts of a large number of developers, all of whom see
> the value in actually caring about our documentation and making it
> accessible to a much larger group of readers. And it has all happened
> while preserving the primacy of the plain-text documentation.
>
> You're not the only consumer of the docs. You may not appreciate the
> improvements that have come, but others certainly do. I do hope that you
> can find it in youself to avoid vandalizing things for everybody else ...?

You wrote it: the fact that some people (including its developers) see
a value in the RST work or the fact that such work made the kernel doc.
accessible to a larger group of readers are not in question here; only
remember that other people (including some developers running into the
"disadventure" of opening an RST doc. from their preferred text editor
and being brought to conclude: "WTH! I need to open a web browser, I
guess...") _use_ such doc. and _do care_ about it, and that what might
be an improvement for some people might look as "vandalizing" to others.

We're talking about readability/accessibility here, but I think similar
considerations apply to other aspects of the doc. such as availability/
completeness (yes, I did hear developers arguing "I won't write such a
doc., because...") and consistency (w.r.t. the doc. itself and sources).

Andrea

>
> Thanks,
>
> jon