Skip to contentSkip to conversation

fs: direct-io: Fixed a Documentation build warn

PATCH In review Madhuparna Bhowmik 3 participants 3 messages Sep 24, 2019 VFS

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 fs: direct-io: Fixed a Documentation build warn

warning: Excess function parameter 'offset' description in 'dio_complete'.
This patch removes offset from the list of arguments from the function header as it not an argument to the function. Adds the description about offset within the code.

Signed-off-by Madhuparna Bhowmik <madhuparnabhowmik04 at gmail.com>
---
 fs/direct-io.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
fs/direct-io.c +1 -1
index ae196784f487..a9cb770f0bc1 100644
@@ -243,7 +243,6 @@ void dio_warn_stale_pagecache(struct file *filp)
 
 /**
  * dio_complete() - called when all DIO BIO I/O has been completed
- * @offset: the byte offset in the file of the completed operation
  *
  * This drops i_dio_count, lets interested parties know that a DIO operation
  * has completed, and calculates the resulting return code for the operation.
@@ -255,6 +254,7 @@ void dio_warn_stale_pagecache(struct file *filp)
  */
 static ssize_t dio_complete(struct dio *dio, ssize_t ret, unsigned int flags)
 {
+	/* offset: the byte offset in the file of the completed operation */
 	loff_t offset = dio->iocb->ki_pos;
 	ssize_t transferred = 0;
 	int err;
Signature · 1 line
2.17.1
#1 lore raw
Quoted 2 lines · Madhuparna Bhowmik

Adds the description about
offset within the code.

Why?

fs/direct-io.c void dio_warn_stale_pagecache(struct file *filp) · line 260

Quoted 8 lines
fs/direct-io.c +1 -0
@@ -255,6 +254,7 @@ void dio_warn_stale_pagecache(struct file *filp)
  */
 static ssize_t dio_complete(struct dio *dio, ssize_t ret, unsigned int flags)
 {
+	/* offset: the byte offset in the file of the completed operation */
 	loff_t offset = dio->iocb->ki_pos;
 	ssize_t transferred = 0;
 	int err;

This is not normal practice within the Linux kernel. I suggest reading section 8 of Documentation/process/coding-style.rst

#2 lore raw
Quoted 6 lines · Matthew Wilcox
Quoted 2 lines · Madhuparna Bhowmik

Adds the description about
offset within the code.

Why?

Quoted 12 lines

fs/direct-io.c void dio_warn_stale_pagecache(struct file *filp) · line 260

Quoted 8 lines
fs/direct-io.c +1 -0
@@ -255,6 +254,7 @@ void dio_warn_stale_pagecache(struct file *filp)
   */
  static ssize_t dio_complete(struct dio *dio, ssize_t ret, unsigned int flags)
  {
+	/* offset: the byte offset in the file of the completed operation */
  	loff_t offset = dio->iocb->ki_pos;
  	ssize_t transferred = 0;
  	int err;

This is not normal practice within the Linux kernel. I suggest reading section 8 of Documentation/process/coding-style.rst

You don't combine documentation and code patches. I don't think you need to add this comment in here.

thanks,
-- Shuah