Skip to contentSkip to conversation

ttp_port: Clean up kernel-docs

PATCH In review Tobin C. Harding 3 participants 10 messages Sep 12, 2018 – Sep 19, 2018

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover ttp_port: Clean up kernel-docs

Hi,

This set is just putting a toe in the water to see if kernel-docs cleanup is wanted in drivers/tty/

While chasing syzkaller bugs I opened up drivers/tty/tty_port.c and noticed that a bunch of the kernel-docs function comments were incorrectly styled. This is the case for more files under drivers/tty/, if fixing this is deemed worthwhile I can add it to my list of jobs to do when my brain is too fried to do anything else.

Changes comments that look like this:

/**
* ptmx_open - open a unix 98 pty master
* @inode: inode of device file
* @filp: file pointer to tty
*
* Allocate a unix98 pty master device from the ptmx driver.
*
* Locking: tty_mutex protects the init_dev work. tty->count should
* protect the rest.
* allocated_ptys_lock handles the list of free pty numbers
*/

static int ptmx_open(struct inode *inode, struct file *filp)

To look like this:

/**
* ptmx_open() - Open a unix 98 pty master.
* @inode: inode of device file
* @filp: file pointer to tty
*
* Allocate a unix98 pty master device from the ptmx driver. *
* Locking: tty_mutex protects the init_dev work. tty->count should
* protect the rest.
* allocated_ptys_lock handles the list of free pty numbers
*/
static int ptmx_open(struct inode *inode, struct file *filp)

This is super trivial clean up - I will not be offended if this is deemed code churn.

thanks,
Tobin.

Tobin C. Harding (3):
tty_port: Remove incorrect whitespace after comments
tty_port: Fix function name and brief desc
tty_port: Fix kernel-docs warnings

 drivers/tty/tty_port.c | 133 ++++++++++++++++++++---------------------
 1 file changed, 65 insertions(+), 68 deletions(-)
Signature · 1 line
2.17.1
#1 lore raw

PATCH 1/3 tty_port: Remove incorrect whitespace after comments

Currently there are a bunch of kernel-doc function comments that have a line of whitespace after the comment and before the function they comment - this is incorrect, there should be no whitespace here.

Remove incorrect whitespace between comment and associated function.

---
 drivers/tty/tty_port.c | 7 -------
 1 file changed, 7 deletions(-)
drivers/tty/tty_port.c +0 -7
index 25d736880013..cb6075096a5b 100644
@@ -279,7 +279,6 @@ EXPORT_SYMBOL(tty_port_put);
  *	Return a refcount protected tty instance or NULL if the port is not
  *	associated with a tty (eg due to close or hangup)
  */
-
 struct tty_struct *tty_port_tty_get(struct tty_port *port)
 {
 	unsigned long flags;
@@ -300,7 +299,6 @@ EXPORT_SYMBOL(tty_port_tty_get);
  *	Associate the port and tty pair. Manages any internal refcounts.
  *	Pass NULL to deassociate a port
  */
-
 void tty_port_tty_set(struct tty_port *port, struct tty_struct *tty)
 {
 	unsigned long flags;
@@ -343,7 +341,6 @@ static void tty_port_shutdown(struct tty_port *port, struct tty_struct *tty)
  *
  *	Caller holds tty lock.
  */
-
 void tty_port_hangup(struct tty_port *port)
 {
 	struct tty_struct *tty;
@@ -399,7 +396,6 @@ EXPORT_SYMBOL_GPL(tty_port_tty_wakeup);
  *	to hide some internal details. This will eventually become entirely
  *	internal to the tty port.
  */
-
 int tty_port_carrier_raised(struct tty_port *port)
 {
 	if (port->ops->carrier_raised == NULL)
@@ -416,7 +412,6 @@ EXPORT_SYMBOL(tty_port_carrier_raised);
  *	to hide some internal details. This will eventually become entirely
  *	internal to the tty port.
  */
-
 void tty_port_raise_dtr_rts(struct tty_port *port)
 {
 	if (port->ops->dtr_rts)
@@ -432,7 +427,6 @@ EXPORT_SYMBOL(tty_port_raise_dtr_rts);
  *	to hide some internal details. This will eventually become entirely
  *	internal to the tty port.
  */
-
 void tty_port_lower_dtr_rts(struct tty_port *port)
 {
 	if (port->ops->dtr_rts)
@@ -464,7 +458,6 @@ EXPORT_SYMBOL(tty_port_lower_dtr_rts);
  *      NB: May drop and reacquire tty lock when blocking, so tty and tty_port
  *      may have changed state (eg., may have been hung up).
  */
-
 int tty_port_block_til_ready(struct tty_port *port,
 				struct tty_struct *tty, struct file *filp)
 {
Signature · 1 line
2.17.1
#2 lore raw

PATCH 2/3 tty_port: Fix function name and brief desc

In reply to Tobin C. Harding

File contains kernel-doc function comments that are not in the correct style.

- Add '()' to function names
- Capitalise brief description and append a full stop.
- Use correct spacing for function name / brief description as per the kernel docs (Documentation/doc-guide/kernel-doc.rst)

/**
* function_name() - Brief description of function.
* @arg1: Describe the first argument.

- Fix spacing for kernel-doc function comments (no tab space after '*').

These changes all touch the same lines so do them in a single patch.

---
 drivers/tty/tty_port.c | 120 ++++++++++++++++++++---------------------
 1 file changed, 59 insertions(+), 61 deletions(-)
drivers/tty/tty_port.c +59 -61
index cb6075096a5b..382282013c9d 100644
@@ -74,7 +74,7 @@ void tty_port_init(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_init);
 
 /**
- * tty_port_link_device - link tty and tty_port
+ * tty_port_link_device() - Link tty and tty_port.
  * @port: tty_port of the device
  * @driver: tty_driver for this device
  * @index: index of the tty
@@ -94,7 +94,7 @@ void tty_port_link_device(struct tty_port *port,
 EXPORT_SYMBOL_GPL(tty_port_link_device);
 
 /**
- * tty_port_register_device - register tty device
+ * tty_port_register_device() - Register tty device.
  * @port: tty_port of the device
  * @driver: tty_driver for this device
  * @index: index of the tty
@@ -113,7 +113,7 @@ struct device *tty_port_register_device(struct tty_port *port,
 EXPORT_SYMBOL_GPL(tty_port_register_device);
 
 /**
- * tty_port_register_device_attr - register tty device
+ * tty_port_register_device_attr() - Register tty device.
  * @port: tty_port of the device
  * @driver: tty_driver for this device
  * @index: index of the tty
@@ -137,7 +137,7 @@ struct device *tty_port_register_device_attr(struct tty_port *port,
 EXPORT_SYMBOL_GPL(tty_port_register_device_attr);
 
 /**
- * tty_port_register_device_attr_serdev - register tty or serdev device
+ * tty_port_register_device_attr_serdev() - Register tty or serdev device.
  * @port: tty_port of the device
  * @driver: tty_driver for this device
  * @index: index of the tty
@@ -169,7 +169,7 @@ struct device *tty_port_register_device_attr_serdev(struct tty_port *port,
 EXPORT_SYMBOL_GPL(tty_port_register_device_attr_serdev);
 
 /**
- * tty_port_register_device_serdev - register tty or serdev device
+ * tty_port_register_device_serdev() - Register tty or serdev device.
  * @port: tty_port of the device
  * @driver: tty_driver for this device
  * @index: index of the tty
@@ -188,7 +188,7 @@ struct device *tty_port_register_device_serdev(struct tty_port *port,
 EXPORT_SYMBOL_GPL(tty_port_register_device_serdev);
 
 /**
- * tty_port_unregister_device - deregister a tty or serdev device
+ * tty_port_unregister_device() - Deregister a tty or serdev device.
  * @port: tty_port of the device
  * @driver: tty_driver for this device
  * @index: index of the tty
@@ -235,7 +235,7 @@ void tty_port_free_xmit_buf(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_free_xmit_buf);
 
 /**
- * tty_port_destroy -- destroy inited port
+ * tty_port_destroy() - Destroy inited port.
  * @port: tty port to be destroyed
  *
  * When a port was initialized using tty_port_init, one has to destroy the
@@ -273,11 +273,11 @@ void tty_port_put(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_put);
 
 /**
- *	tty_port_tty_get	-	get a tty reference
- *	@port: tty port
+ * tty_port_tty_get() - Get a tty reference.
+ * @port: tty port
  *
- *	Return a refcount protected tty instance or NULL if the port is not
- *	associated with a tty (eg due to close or hangup)
+ * Return a refcount protected tty instance or NULL if the port is not
+ * associated with a tty (eg due to close or hangup)
  */
 struct tty_struct *tty_port_tty_get(struct tty_port *port)
 {
@@ -292,12 +292,12 @@ struct tty_struct *tty_port_tty_get(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_tty_get);
 
 /**
- *	tty_port_tty_set	-	set the tty of a port
- *	@port: tty port
- *	@tty: the tty
+ * tty_port_tty_set - Set the tty of a port.
+ * @port: tty port
+ * @tty: the tty
  *
- *	Associate the port and tty pair. Manages any internal refcounts.
- *	Pass NULL to deassociate a port
+ * Associate the port and tty pair. Manages any internal refcounts.
+ * Pass NULL to deassociate a port
  */
 void tty_port_tty_set(struct tty_port *port, struct tty_struct *tty)
 {
@@ -333,13 +333,13 @@ static void tty_port_shutdown(struct tty_port *port, struct tty_struct *tty)
 }
 
 /**
- *	tty_port_hangup		-	hangup helper
- *	@port: tty port
+ * tty_port_hangup() - Hangup helper.
+ * @port: tty port
  *
- *	Perform port level tty hangup flag and count changes. Drop the tty
- *	reference.
+ * Perform port level tty hangup flag and count changes. Drop the tty
+ * reference.
  *
- *	Caller holds tty lock.
+ * Caller holds tty lock.
  */
 void tty_port_hangup(struct tty_port *port)
 {
@@ -362,8 +362,7 @@ void tty_port_hangup(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_hangup);
 
 /**
- * tty_port_tty_hangup - helper to hang up a tty
- *
+ * tty_port_tty_hangup() - Helper to hang up a tty.
  * @port: tty port
  * @check_clocal: hang only ttys with CLOCAL unset?
  */
@@ -378,8 +377,7 @@ void tty_port_tty_hangup(struct tty_port *port, bool check_clocal)
 EXPORT_SYMBOL_GPL(tty_port_tty_hangup);
 
 /**
- * tty_port_tty_wakeup - helper to wake up a tty
- *
+ * tty_port_tty_wakeup() - Helper to wake up a tty.
  * @port: tty port
  */
 void tty_port_tty_wakeup(struct tty_port *port)
@@ -389,12 +387,12 @@ void tty_port_tty_wakeup(struct tty_port *port)
 EXPORT_SYMBOL_GPL(tty_port_tty_wakeup);
 
 /**
- *	tty_port_carrier_raised	-	carrier raised check
- *	@port: tty port
+ * tty_port_carrier_raised() - Carrier raised check.
+ * @port: tty port
  *
- *	Wrapper for the carrier detect logic. For the moment this is used
- *	to hide some internal details. This will eventually become entirely
- *	internal to the tty port.
+ * Wrapper for the carrier detect logic. For the moment this is used
+ * to hide some internal details. This will eventually become entirely
+ * internal to the tty port.
  */
 int tty_port_carrier_raised(struct tty_port *port)
 {
@@ -405,12 +403,12 @@ int tty_port_carrier_raised(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_carrier_raised);
 
 /**
- *	tty_port_raise_dtr_rts	-	Raise DTR/RTS
- *	@port: tty port
+ * tty_port_raise_dtr_rts() - Raise DTR/RTS.
+ * @port: tty port
  *
- *	Wrapper for the DTR/RTS raise logic. For the moment this is used
- *	to hide some internal details. This will eventually become entirely
- *	internal to the tty port.
+ * Wrapper for the DTR/RTS raise logic. For the moment this is used
+ * to hide some internal details. This will eventually become entirely
+ * internal to the tty port.
  */
 void tty_port_raise_dtr_rts(struct tty_port *port)
 {
@@ -420,12 +418,12 @@ void tty_port_raise_dtr_rts(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_raise_dtr_rts);
 
 /**
- *	tty_port_lower_dtr_rts	-	Lower DTR/RTS
- *	@port: tty port
+ * tty_port_lower_dtr_rts() - Lower DTR/RTS.
+ * @port: tty port
  *
- *	Wrapper for the DTR/RTS raise logic. For the moment this is used
- *	to hide some internal details. This will eventually become entirely
- *	internal to the tty port.
+ * Wrapper for the DTR/RTS raise logic. For the moment this is used
+ * to hide some internal details. This will eventually become entirely
+ * internal to the tty port.
  */
 void tty_port_lower_dtr_rts(struct tty_port *port)
 {
@@ -435,28 +433,28 @@ void tty_port_lower_dtr_rts(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_lower_dtr_rts);
 
 /**
- *	tty_port_block_til_ready	-	Waiting logic for tty open
- *	@port: the tty port being opened
- *	@tty: the tty device being bound
- *	@filp: the file pointer of the opener or NULL
+ * tty_port_block_til_ready() -	Waiting logic for tty open.
+ * @port: the tty port being opened
+ * @tty: the tty device being bound
+ * @filp: the file pointer of the opener or NULL
  *
- *	Implement the core POSIX/SuS tty behaviour when opening a tty device.
- *	Handles:
- *		- hangup (both before and during)
- *		- non blocking open
- *		- rts/dtr/dcd
- *		- signals
- *		- port flags and counts
+ * Implement the core POSIX/SuS tty behaviour when opening a tty device.
+ * Handles:
+ *  - hangup (both before and during)
+ *  - non blocking open
+ *  - rts/dtr/dcd
+ *  - signals
+ *  - port flags and counts
  *
- *	The passed tty_port must implement the carrier_raised method if it can
- *	do carrier detect and the dtr_rts method if it supports software
- *	management of these lines. Note that the dtr/rts raise is done each
- *	iteration as a hangup may have previously dropped them while we wait.
+ * The passed tty_port must implement the carrier_raised method if it can
+ * do carrier detect and the dtr_rts method if it supports software
+ * management of these lines. Note that the dtr/rts raise is done each
+ * iteration as a hangup may have previously dropped them while we wait.
  *
- *	Caller holds tty lock.
+ * Caller holds tty lock.
  *
- *      NB: May drop and reacquire tty lock when blocking, so tty and tty_port
- *      may have changed state (eg., may have been hung up).
+ * NB: May drop and reacquire tty lock when blocking, so tty and tty_port
+ * may have changed state (eg., may have been hung up).
  */
 int tty_port_block_til_ready(struct tty_port *port,
 				struct tty_struct *tty, struct file *filp)
@@ -623,7 +621,7 @@ void tty_port_close_end(struct tty_port *port, struct tty_struct *tty)
 EXPORT_SYMBOL(tty_port_close_end);
 
 /**
- * tty_port_close
+ * tty_port_close()
  *
  * Caller holds tty lock
  */
@@ -640,7 +638,7 @@ void tty_port_close(struct tty_port *port, struct tty_struct *tty,
 EXPORT_SYMBOL(tty_port_close);
 
 /**
- * tty_port_install - generic tty->ops->install handler
+ * tty_port_install() - Generic tty->ops->install handler.
  * @port: tty_port of the device
  * @driver: tty_driver for this device
  * @tty: tty to be installed
@@ -658,7 +656,7 @@ int tty_port_install(struct tty_port *port, struct tty_driver *driver,
 EXPORT_SYMBOL_GPL(tty_port_install);
 
 /**
- * tty_port_open
+ * tty_port_open()
  *
  * Caller holds tty lock.
  *
Signature · 1 line
2.17.1
#3 lore raw

Re: [PATCH 2/3] tty_port: Fix function name and brief desc

Quoted 5 lines · Tobin C. Harding

File contains kernel-doc function comments that are not in the correct style.

- Add '()' to function names
- Capitalise brief description and append a full stop.

Cleaning up these comments may not be a bad idea, but I have my doubts about this particular item. Many descriptions aren't full sentences and still won't be even if you capitalise and slap a full stop there, for example:

Quoted 2 lines

- * tty_port_hangup - hangup helper
+ * tty_port_hangup() - Hangup helper.

There's no requirement to use full sentences, and the old kernel-doc nano doc uses incomplete ones, as do most (?) kernel-doc comments throughout the kernel.

I'd just drop this part of the patch.

Quoted 7 lines

- Use correct spacing for function name / brief description as per the kernel docs (Documentation/doc-guide/kernel-doc.rst)

/**
* function_name() - Brief description of function.
* @arg1: Describe the first argument.

Quoted 5 lines

- Fix spacing for kernel-doc function comments (no tab space after '*').

These changes all touch the same lines so do them in a single patch.

Thanks,
Johan

#4 lore raw

Re: [PATCH 2/3] tty_port: Fix function name and brief desc

Quoted 12 lines · Johan Hovold
Quoted 5 lines · Tobin C. Harding

File contains kernel-doc function comments that are not in the correct style.

- Add '()' to function names
- Capitalise brief description and append a full stop.

Cleaning up these comments may not be a bad idea, but I have my doubts about this particular item. Many descriptions aren't full sentences and still won't be even if you capitalise and slap a full stop there, for example:

Quoted 8 lines
Quoted 2 lines

- * tty_port_hangup - hangup helper
+ * tty_port_hangup() - Hangup helper.

There's no requirement to use full sentences, and the old kernel-doc nano doc uses incomplete ones, as do most (?) kernel-doc comments throughout the kernel.

I'd just drop this part of the patch.

Ok, sounds good to me. Thanks for the review.

Tobin

#5 lore raw

Re: [PATCH 2/3] tty_port: Fix function name and brief desc

In reply to Tobin C. Harding

drivers/tty/tty_port.c void tty_port_free_xmit_buf(struct tty_port *port) · line 238

Quoted 6 lines · Tobin C. Harding
drivers/tty/tty_port.c +1 -1
@@ -235,7 +235,7 @@ void tty_port_free_xmit_buf(struct tty_port *port)
 EXPORT_SYMBOL(tty_port_free_xmit_buf);
 
 /**
- * tty_port_destroy -- destroy inited port
+ * tty_port_destroy() - Destroy inited port.

Ok, using () for a function name, that's fine, but then you do:

drivers/tty/tty_port.c struct tty_struct *tty_port_tty_get(struct tty_port *port) · line 295

Quoted 5 lines
drivers/tty/tty_port.c +1 -3
 /**
- *	tty_port_tty_set	-	set the tty of a port
- *	@port: tty port
- *	@tty: the tty
+ * tty_port_tty_set - Set the tty of a port.

Oops, not here. Consistency is the key.

thanks,

greg k-h

#6 lore raw

PATCH 3/3 tty_port: Fix kernel-docs warnings

In reply to Tobin C. Harding

Currently extracting the kernel-docs causes a six warnings of type

warning: Function parameter or member 'foo' not described in 'bar'

Add function parameter descriptions to the function kernel-docs.

---
 drivers/tty/tty_port.c | 6 ++++++
 1 file changed, 6 insertions(+)
drivers/tty/tty_port.c +6 -0
index 382282013c9d..2444ed90b93d 100644
@@ -622,6 +622,9 @@ EXPORT_SYMBOL(tty_port_close_end);
 
 /**
  * tty_port_close()
+ * @port: tty port
+ * @tty: the tty
+ * @filp: the file pointer
  *
  * Caller holds tty lock
  */
@@ -657,6 +660,9 @@ EXPORT_SYMBOL_GPL(tty_port_install);
 
 /**
  * tty_port_open()
+ * @port: tty port
+ * @tty: the tty
+ * @filp: the file pointer
  *
  * Caller holds tty lock.
  *
Signature · 1 line
2.17.1
#7 lore raw

Re: [PATCH 3/3] tty_port: Fix kernel-docs warnings

Quoted 10 lines · Tobin C. Harding

Currently extracting the kernel-docs causes a six warnings of type

warning: Function parameter or member 'foo' not described in 'bar'

Add function parameter descriptions to the function kernel-docs.

---
 drivers/tty/tty_port.c | 6 ++++++
 1 file changed, 6 insertions(+)

As I didn't take patch 2/3, this one doesn't apply :(

thanks,

greg k-h

#8 lore raw

Re: [PATCH 3/3] tty_port: Fix kernel-docs warnings

Quoted 5 lines · Greg Kroah-Hartman
Quoted 4 lines · Tobin C. Harding

Currently extracting the kernel-docs causes a six warnings of type

warning: Function parameter or member 'foo' not described in 'bar'

Quoted 8 lines
Quoted 6 lines

Add function parameter descriptions to the function kernel-docs.

---
 drivers/tty/tty_port.c | 6 ++++++
 1 file changed, 6 insertions(+)

As I didn't take patch 2/3, this one doesn't apply :(

Oh I thought this whole set would have been ignored because of comments on it. I've been working on doing these changes for all of drivers/tty/

Thanks for reviewing and taking the first patch. I'll be sure to rebase.

thanks,
Tobin.

#9 lore raw

Re: [PATCH 3/3] tty_port: Fix kernel-docs warnings

Quoted 13 lines · Tobin C. Harding
Quoted 12 lines · Greg Kroah-Hartman
Quoted 10 lines · Tobin C. Harding

Currently extracting the kernel-docs causes a six warnings of type

warning: Function parameter or member 'foo' not described in 'bar'

Add function parameter descriptions to the function kernel-docs.

---
 drivers/tty/tty_port.c | 6 ++++++
 1 file changed, 6 insertions(+)
Quoted 4 lines
Quoted 1 line

As I didn't take patch 2/3, this one doesn't apply :(

Oh I thought this whole set would have been ignored because of comments on it.

Not at all, kerneldoc cleanups are great to have!

Quoted 1 line

I've been working on doing these changes for all of drivers/tty/

That's good, it needs it, thanks.

greg k-h