All of lore.kernel.org
 help / color / mirror / Atom feed
From: Al Viro <viro@zeniv.linux.org.uk>
To: "Tobin C. Harding" <me@tobin.cc>
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: Wed, 3 Apr 2019 20:47:21 +0100	[thread overview]
Message-ID: <20190403194720.GY2217@ZenIV.linux.org.uk> (raw)
In-Reply-To: <20190402192520.GA6285@eros.localdomain>

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...

  reply	other threads:[~2019-04-03 19:47 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 [this message]
2019-04-03 20:59         ` Tobin C. Harding
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=20190403194720.GY2217@ZenIV.linux.org.uk \
    --to=viro@zeniv.linux.org.uk \
    --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=me@tobin.cc \
    --cc=neilb@suse.com \
    --cc=rdunlap@infradead.org \
    --cc=tobin@kernel.org \
    /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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.