[PATCH v3 06/24] fs: Update function docstring for simple_write_end()

From: "Tobin C. Harding" <tobin@kernel.org>
To: Al Viro <viro@zeniv.linux.org.uk>
Cc: "Tobin C. Harding" <tobin@kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	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: [PATCH v3 06/24] fs: Update function docstring for simple_write_end()
Date: Wed, 27 Mar 2019 16:16:59 +1100	[thread overview]
Message-ID: <20190327051717.23225-7-tobin@kernel.org> (raw)
In-Reply-To: <20190327051717.23225-1-tobin@kernel.org>

Shinx emits a warning due to an extra function parameter in the current
function docstring for simple_write_end().  While we are fixing this
warning we might as well clean up the whole function docstring for this
function.

The current member descriptions are readable in text and also ok in
HTML.  When vfs.txt is converted to use RST format these member
descriptions could be improved with a reference to struct
address_space_operations docs in that file.

Update and cleanup docstring for simple_write_end()

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 fs/libfs.c | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/fs/libfs.c b/fs/libfs.c
index 0fb590d79f30..36af25b9b2a3 100644
--- a/fs/libfs.c
+++ b/fs/libfs.c
@@ -448,9 +448,8 @@ int simple_write_begin(struct file *file, struct address_space *mapping,
 EXPORT_SYMBOL(simple_write_begin);
 
 /**
- * simple_write_end - .write_end helper for non-block-device FSes
- * @available: See .write_end of address_space_operations
- * @file: 		"
+ * simple_write_end() - .write_end helper for non-block-device FSes
+ * @file: See .write_end of &struct address_space_operations
  * @mapping: 		"
  * @pos: 		"
  * @len: 		"
@@ -458,17 +457,21 @@ EXPORT_SYMBOL(simple_write_begin);
  * @page: 		"
  * @fsdata: 		"
  *
- * simple_write_end does the minimum needed for updating a page after writing is
- * done. It has the same API signature as the .write_end of
- * address_space_operations vector. So it can just be set onto .write_end for
- * FSes that don't need any other processing. i_mutex is assumed to be held.
- * Block based filesystems should use generic_write_end().
- * NOTE: Even though i_size might get updated by this function, mark_inode_dirty
- * is not called, so a filesystem that actually does store data in .write_inode
- * should extend on what's done here with a call to mark_inode_dirty() in the
- * case that i_size has changed.
+ * Does the minimum needed for updating a page after writing is done.
+ * It has the same API signature as the .write_end member of &struct
+ * address_space_operations vector.  So it can just be set onto
+ * .write_end for FSes that don't need any other processing.  Block
+ * based filesystems should use generic_write_end().
+ *
+ * NOTE: Even though i_size might get updated by this function,
+ * mark_inode_dirty() is not called, so a filesystem that actually does
+ * store data in .write_inode should extend on what's done here with a
+ * call to mark_inode_dirty() in the case that i_size has changed.
  *
  * Use *ONLY* with simple_readpage()
+ *
+ * Context: Caller must hold i_mutex
+ * Return: @copied argument unmodified.
  */
 int simple_write_end(struct file *file, struct address_space *mapping,
 			loff_t pos, unsigned len, unsigned copied,
-- 
2.21.0

