Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Wed, 20 Mar 2019 10:42:00 +1100
From:   "Tobin C. Harding" <me@tobin.cc>
To:     "Tobin C. Harding" <tobin@kernel.org>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Randy Dunlap <rdunlap@infradead.org>,
        linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org,
        linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 09/13] docs: filesystems: vfs: Add code-block and
 txt->RST
Message-ID: <20190319234200.GA13178@eros.localdomain>
References: <20190318231437.1666-1-tobin@kernel.org>
 <20190318231437.1666-10-tobin@kernel.org>
 <20190319013526.GA30001@eros.localdomain>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20190319013526.GA30001@eros.localdomain>
User-Agent: Mutt/1.11.4 (2019-03-13)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

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.