linux-kernel - Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

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-next>] [day] [month] [year] [list]

Message-ID: <20704.1556031146@warthog.procyon.org.uk>
Date:   Tue, 23 Apr 2019 15:52:26 +0100
From:   David Howells <dhowells@...hat.com>
To:     Mike Snitzer <snitzer@...hat.com>
Cc:     dhowells@...hat.com, Peter Zijlstra <peterz@...radead.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Jonathan Corbet <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org, linux-arch@...r.kernel.org
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

Mike Snitzer <snitzer@...hat.com> wrote:

> Peter Zijlstra <peterz@...radead.org> wrote:
> 
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/
> 
> Right, but these changes aren't meant for our benefit.  They are for
> users who get cleaner web accessible Linux kernel docs.  Seems the
> decision has been made that the users' benefit, and broader
> modernization of Linux docs, outweighs the inconvenience for engineers
> who maintain the content of said documentation.

Whilst I can sympathise with Mauro and Jon - and appreciate the hard work
they've put into this, I do think that the engineers dealing directly with the
kernel code should be considered the primary audience.

There've been some changes that I've particularly objected to, such as
removing contents lists from files and replacing them with markup like:

	.. contents:: :local:

This actually impedes use of the file.  It should not be necessary to build
the docs to get that for ordinary use.

Anyway, the biggest doc issue in the kernel isn't addressed by the conversion
to ReST: and that is that most people don't seem interested in documenting
stuff - whether because writing documentation isn't as fun as writing code or
the fact that English isn't their native language, I don't know.  I can
sympathise more with the latter.

Kerneldoc is a start - and probably means that a lot of API functions are at
least slightly documented - but too many APIs are not mentioned in the
Documentation directory at all.  Remember: if you can't describe it, it's
probably wrong!

I'm not sure what we could do about this, but it would probably have to be
imposed from the top: no more undocumented APIs.  Any new API must come with
documentation; changes to APIs must include changes to the documentation.

If you really want to upset people, you could add: anyone who wants to alter
an already existing undocumented API must supply documentation for the whole
API (but that could be considered a bit cruel).

And anyone who says "But the code is the documentation!" needs to consider
carefully what happens to their code after it has been trampled, generalised,
split, combined, renormalised, cthulhuised, janitorised and had parts of it
migrate.

</rant>

And now, after that, I think a fresh cup of tea is called for!

David