linux-kernel - Re: [PATCH v2 09/13] docs: filesystems: vfs: Add code-block and txt->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 for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20190319234200.GA13178@eros.localdomain>
Date:   Wed, 20 Mar 2019 10:42:00 +1100
From:   "Tobin C. Harding" <me@...in.cc>
To:     "Tobin C. Harding" <tobin@...nel.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Randy Dunlap <rdunlap@...radead.org>,
        linux-doc@...r.kernel.org, linux-fsdevel@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 09/13] docs: filesystems: vfs: Add code-block and
 txt->RST

On Tue, Mar 19, 2019 at 12:35:26PM +1100, Tobin C. Harding wrote:
> On Tue, Mar 19, 2019 at 10:14:33AM +1100, Tobin C. Harding wrote:
> > Use code-block for C source code.  With this in place we can rename the
> > .txt file to  .rst.  This introduces a few warnings that will be fixed
> > in proceeding patches.
> > 
> > Add '.. code-block:: c' to C source code snippets.  Rename the file to
> > use rst file suffix.
> 
> I just realised that a better way to document these structs is to do so
> above the actual struct definition in the source file then include those
> docs in the documentation file.

Please either drop this set or only consider patches 1-8 for merge.  I
haven't worked out _exactly_ how to move the docs from
Documentation/filesystems/vfs to the source code files but I've played
with it enough now to feel it is possible and it is definitely better.
Just have to massage Sphinx into agreeing with me.

I thought the whole reason we have docstring comments is because we all
agreed that docs close to code hove more chance of staying relevant.
vfs.txt proves that nicely (docs in it from 2.6 for structs that are
actively used and developed).

Sorry for the noise, one day I'll work these things out _before_ sending
the patches :)

thanks,
Tobin.