From: "Tobin C. Harding" <me@tobin.cc>
To: Al Viro <viro@zeniv.linux.org.uk>
Cc: Jonathan Corbet <corbet@lwn.net>,
"Tobin C. Harding" <tobin@kernel.org>,
Mauro Carvalho Chehab <mchehab@s-opensource.com>,
Neil Brown <neilb@suse.com>, Randy Dunlap <rdunlap@infradead.org>,
linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH v3 00/24] Convert vfs.txt to vfs.rst
Date: Thu, 4 Apr 2019 07:59:38 +1100 [thread overview]
Message-ID: <20190403205938.GA23288@eros.localdomain> (raw)
In-Reply-To: <20190403194720.GY2217@ZenIV.linux.org.uk>
On Wed, Apr 03, 2019 at 08:47:21PM +0100, Al Viro wrote:
> On Wed, Apr 03, 2019 at 06:25:20AM +1100, Tobin C. Harding wrote:
> > On Tue, Apr 02, 2019 at 05:48:24PM +0100, Al Viro wrote:
> > > On Tue, Apr 02, 2019 at 09:49:34AM -0600, Jonathan Corbet wrote:
> > > > On Wed, 27 Mar 2019 16:16:53 +1100
> > > > "Tobin C. Harding" <tobin@kernel.org> wrote:
> > > >
> > > > > Hi Al,
> > > > >
> > > > > This series converts the VFS file Documentation/filesystems/vfs.txt to
> > > > > reStructuredText format. Please consider taking this series through
> > > > > your tree as apposed to Jon's tree because this set makes a fair amount
> > > > > of changes to VFS files (and also the VFS tree and docs tree are out of
> > > > > sync right now with the recent work by Mauro and Neil).
> > > >
> > > > Al, do you have any thoughts on how you want to handle this? I was about
> > > > to apply Jeff Layton's vfs.txt update, but would rather not create
> > > > conflicts unnecessarily. Let me know if you'd like me to pick this work
> > > > up.
> > >
> > > Frankly, I would rather see that file be eventually replaced by something
> > > saner, and I'm not talking about the format.
> >
> > Are you able to extrapolate on this comment please? Is this something
> > someone new to the VFS (me) can do with a little nudge in the right
> > direction or is this something that needs thorough knowledge of the VFS?
>
> Put it that way - IMO the best way to do it is not a list of methods with
> explanations what each does, but a bunch of per-data structure documents
> describing their life cycles. The fundamental ones for VFS would be
> * inode
> * dentry
> * super_block
> * (vfs)mount
> * file
> * files_struct
> Having a list of methods is nice, but those would be better off with short
> description along with "see <document> for details, including the locking,
> etc."; said short descriptions make little sense without the background...
Ok, got it. Thanks.
Tobin
next prev parent reply other threads:[~2019-04-03 21:00 UTC|newest]
Thread overview: 43+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-03-27 5:16 [PATCH v3 00/24] Convert vfs.txt to vfs.rst Tobin C. Harding
2019-03-27 5:16 ` [PATCH v3 01/24] vfs: Remove trailing whitespace Tobin C. Harding
2019-03-27 5:16 ` [PATCH v3 02/24] vfs: Clean up VFS data structure declarations Tobin C. Harding
2019-03-27 5:16 ` [PATCH v3 03/24] fs: Update function docstring for dio_complete() Tobin C. Harding
2019-03-27 5:16 ` [PATCH v3 04/24] fs: Add docstrings to exported functions Tobin C. Harding
2019-03-27 5:16 ` [PATCH v3 05/24] fs: Guard unusual text with backticks Tobin C. Harding
2019-03-27 5:16 ` [PATCH v3 06/24] fs: Update function docstring for simple_write_end() Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 07/24] fs: Fix function docstring for posix_acl_update_mode() Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 08/24] dcache: Remove trailing whitespace Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 09/24] dcache: Fix i.e. usage in coments Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 10/24] dcache: Fix e.g. usage in comment Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 11/24] dcache: Fix docstring comment for d_drop() Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 12/24] dcache: Fix non-docstring comments Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 13/24] dcache: Clean up function docstrings Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 14/24] dcache: Clean up function docstring members Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 15/24] docs: filesystems: vfs: Remove space before tab Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 16/24] docs: filesystems: vfs: Use uniform space after period Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 17/24] docs: filesystems: vfs: Use 72 character column width Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 18/24] docs: filesystems: vfs: Use uniform spacing around headings Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 19/24] docs: filesystems: vfs: Use correct initial heading Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 20/24] docs: filesystems: vfs: Use SPDX identifier Tobin C. Harding
2019-04-01 5:43 ` Mukesh Ojha
2019-03-27 5:17 ` [PATCH v3 21/24] docs: filesystems: vfs: Fix pre-amble indentation Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 22/24] fs: Copy documentation to struct declarations Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 23/24] dcache: Copy documentation to struct declaration Tobin C. Harding
2019-03-27 5:17 ` [PATCH v3 24/24] docs: Convert vfs.txt to reStructuredText format Tobin C. Harding
2019-03-27 5:24 ` [PATCH v3 00/24] Convert vfs.txt to vfs.rst Joe Perches
2019-03-27 6:26 ` Tobin C. Harding
2019-04-02 15:49 ` Jonathan Corbet
2019-04-02 16:48 ` Al Viro
2019-04-02 17:54 ` Al Viro
2019-04-02 19:08 ` Al Viro
2019-04-02 23:36 ` Ian Kent
2019-04-02 23:56 ` Ian Kent
2019-04-03 0:55 ` NeilBrown
2019-04-03 19:35 ` Al Viro
2019-04-04 6:30 ` Ian Kent
2019-04-03 23:28 ` Ian Kent
2019-04-02 19:25 ` Tobin C. Harding
2019-04-03 19:47 ` Al Viro
2019-04-03 20:59 ` Tobin C. Harding [this message]
2019-04-03 1:00 ` NeilBrown
2019-04-03 1:44 ` Al Viro
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190403205938.GA23288@eros.localdomain \
--to=me@tobin.cc \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@s-opensource.com \
--cc=neilb@suse.com \
--cc=rdunlap@infradead.org \
--cc=tobin@kernel.org \
--cc=viro@zeniv.linux.org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).