Message-Id: <20190327051717.23225-1-tobin@kernel.org>
Date:   Wed, 27 Mar 2019 16:16:53 +1100
From:   "Tobin C. Harding" <tobin@...nel.org>
To:     Al Viro <viro@...iv.linux.org.uk>
Cc:     "Tobin C. Harding" <tobin@...nel.org>,
        Jonathan Corbet <corbet@....net>,
        Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Neil Brown <neilb@...e.com>,
        Randy Dunlap <rdunlap@...radead.org>,
        linux-doc@...r.kernel.org, linux-fsdevel@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: [PATCH v3 00/24] Convert vfs.txt to vfs.rst


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

Excluding patch 2, this set is whitespace and documentation fixes only.

Why 25 patches to convert one simple file?  There is a bunch of clean up
to VFS docs in here.  I have attempted to make review easier by breaking
changes into very discreet patches favouring a single 'type' of change
per patch, even more so than usual with code changes.  By doing so I
hope reviewers are able to parse the diff without having to think too
much.  I also try to state in the commit logs if a patch makes extra
trivial changes to further ease the review process.  There are however a
couple of patches here that make considerable changes to VFS files
(particularly include/linux/fs.h and include/linux/dcache.h); these will
likely require a little more attention when reviewing please, there are 3:

 vfs: Clean up VFS data structure declarations

Adds function names to VFS ops methods (i.e. sturct members that are
function pointers).

 fs: Copy documentation to struct declarations
 dcache: Copy documentation to struct declaration

Along with the final patch these two patches make up the meat of this
series.  They add docstring comments to the core VFS data structures
declared in the headers mentioned above.  The docs used are based on
those currently present in vfs.txt if available or collected by reading
the source code.  Unfortunately various members remain undocumented (and
marked TODO).  I am new to the VFS, I lent towards leaving a 'TODO'
rather than writing wrong/vague documentation.

Of note also is that Sphinx doesn't currently really support documenting
'methods'.  The docs added in this series parse (in my opinion)
reasonable well in both text and HTML.  The layout is however very
slightly different from other places in the kernel documentation.  I
have CC'd Jon (for obvious reasons) and Jani (because of previous
discussion on this topic on LKML) on the relevant patches.

This version is considerably different to v2 because it was not
until after posting that I realised that we could put the docs in the
header files along with the struct declarations.  The justification for
doing so is that documentation far away from source code tends to go
stale, currently the vfs.txt documents core VFS data structures with
some references as old as v2.6 kernel.


Patch 1 - fs.h preparation
Patch 2 - Adds some parameter names to ops struct methods and fixes
          whitespace issues withthe struct declarations.
Patch 3-7 - Fix Sphinx warnings in preparation for working on VFS docs.
Patch 8 - dcache.[ch] preparation.
Patch 9-10 - Minor grammar fixes.
Patch 11 - Cleans up docstring for d_drop(), __d_drop(), and ___d_drop().
Patch 12 - Does [minor] comment clean up in non-docstring comments.
Patch 13 - Improves the docstrings for the dcache.

I recently posted an RFC set attempting to make slab objects movable,
hopefully we can use this to make slab dentry objects movable.  This
series was motivated by trying to grok the dcache in an attempt to do
so.

Patch 14 - Does (possibly anal) cleanup of docstring function
           parameters.  Done as a separate patch to reduce the thought
           required to review the previous patch.  Should, hopefully, be
           trivial to review.
Patch 15-21 - Does preparatory fixes to vfs.txt ready for RST conversion,
              these are as they were in v2 including tested-by tag from
	      Randy.
Patch 22 - As mentioned above, adds docstring documentation to the
           core VFS data structure struct declarations in fs.h
Patch 23 - Does the same for struct dentry declaration in dcache.h
Patch 24 - Does the actual reStructuredText conversion.

Building on top of Mauro's work updating
Documentation/filesystems/index.rst this includes the new vfs.rst at the
top of the current index.rst.  This is justified since vfs.rst is an
overview of the VFS.  This does however mean that some types are
included in the rst doc books more than once.

I got a little confused by the iopoll() method of file_operations while
checking this series against different trees.  If I got it right, iopoll
is _gone_ from the VFS tree so it is _not_ in this set.


Thanks for taking the time to read this.

					Tobin


Changes since v2:
 - Rebased onto Al's VFS tree
 - Fix Sphinx warnings for fs (these were done against the tip of docs
   tree before rebasing on the VFS tree).
 - Clean up dcache docstrings
 - Add docstrings to struct declarations (include/linux[fs.h,dcache.h])

Changes since v1:

 - Re-base onto commit 9834857754ff ("doc:it_IT: translations for documents in process/")
 - Add 'Tested-by:' tag for Randy (thanks!)


Tobin C. Harding (24):
  vfs: Remove trailing whitespace
  vfs: Clean up VFS data structure declarations
  fs: Update function docstring for dio_complete()
  fs: Add docstrings to exported functions
  fs: Guard unusual text with backticks
  fs: Update function docstring for simple_write_end()
  fs: Fix function docstring for posix_acl_update_mode()
  dcache: Remove trailing whitespace
  dcache: Fix i.e. usage in coments
  dcache: Fix e.g. usage in comment
  dcache: Fix docstring comment for d_drop()
  dcache: Fix non-docstring comments
  dcache: Clean up function docstrings
  dcache: Clean up function docstring members
  docs: filesystems: vfs: Remove space before tab
  docs: filesystems: vfs: Use uniform space after period.
  docs: filesystems: vfs: Use 72 character column width
  docs: filesystems: vfs: Use uniform spacing around headings
  docs: filesystems: vfs: Use correct initial heading
  docs: filesystems: vfs: Use SPDX identifier
  docs: filesystems: vfs: Fix pre-amble indentation
  fs: Copy documentation to struct declarations
  dcache: Copy documentation to struct declaration
  docs: Convert vfs.txt to reStructuredText format

 Documentation/filesystems/index.rst |   6 +
 Documentation/filesystems/porting   |  10 +-
 Documentation/filesystems/vfs.rst   | 426 ++++++++++++
 Documentation/filesystems/vfs.txt   | 502 +++++++-------
 fs/dcache.c                         | 469 +++++++------
 fs/direct-io.c                      |   4 +-
 fs/file_table.c                     |  23 +-
 fs/libfs.c                          |  27 +-
 fs/posix_acl.c                      |  16 +-
 include/linux/dcache.h              | 272 ++++++--
 include/linux/fs.h                  | 993 +++++++++++++++++++++++++---
 11 files changed, 2112 insertions(+), 636 deletions(-)
 create mode 100644 Documentation/filesystems/vfs.rst

-- 
2.21.0

Powered by blists - more mailing lists