[PATCH] tracefs: Fix kernel-doc warnings

[PATCH] tracefs: Fix kernel-doc warnings

[Matthew Wilcox (Oracle)]

Move the per-member documentation into the header to fix the complaints
from kernel-doc.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 fs/tracefs/event_inode.c | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/fs/tracefs/event_inode.c b/fs/tracefs/event_inode.c
index da8d2e73cc47..7ca3857ddb89 100644
--- a/fs/tracefs/event_inode.c
+++ b/fs/tracefs/event_inode.c
@@ -37,6 +37,9 @@ struct eventfs_inode {
  * @ei:		list of files and directories within directory
  * @fop:	file_operations for file or directory
  * @iop:	inode_operations for file or directory
+ * @del_list:	list of eventfs_file to delete
+ * @rcu:	eventfs_file to delete
+ * @is_freed:	Non-zero if @del_list or @rcu is active
  * @data:	something that the caller will want to get to later on
  * @mode:	the permission that the file or directory should have
  */
@@ -49,9 +52,9 @@ struct eventfs_file {
 	const struct file_operations	*fop;
 	const struct inode_operations	*iop;
 	union {
-		struct list_head	del_list; /* list of eventfs_file to delete */
-		struct rcu_head		rcu; /* eventfs_file to delete */
-		unsigned long		is_freed; /* Freed if one of the above is set */
+		struct list_head	del_list;
+		struct rcu_head		rcu;
+		unsigned long		is_freed;
 	};
 	void				*data;
 	umode_t				mode;
-- 
2.40.1

Re: [PATCH] tracefs: Fix kernel-doc warnings

[Steven Rostedt]

On Fri, 18 Aug 2023 21:14:13 +0100
"Matthew Wilcox (Oracle)" <willy@infradead.org> wrote:

> Move the per-member documentation into the header to fix the complaints
> from kernel-doc.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> ---
>  fs/tracefs/event_inode.c | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)
> 
> diff --git a/fs/tracefs/event_inode.c b/fs/tracefs/event_inode.c
> index da8d2e73cc47..7ca3857ddb89 100644
> --- a/fs/tracefs/event_inode.c
> +++ b/fs/tracefs/event_inode.c
> @@ -37,6 +37,9 @@ struct eventfs_inode {
>   * @ei:		list of files and directories within directory
>   * @fop:	file_operations for file or directory
>   * @iop:	inode_operations for file or directory
> + * @del_list:	list of eventfs_file to delete
> + * @rcu:	eventfs_file to delete
> + * @is_freed:	Non-zero if @del_list or @rcu is active
>   * @data:	something that the caller will want to get to later on
>   * @mode:	the permission that the file or directory should have
>   */
> @@ -49,9 +52,9 @@ struct eventfs_file {
>  	const struct file_operations	*fop;
>  	const struct inode_operations	*iop;
>  	union {
> -		struct list_head	del_list; /* list of eventfs_file to delete */
> -		struct rcu_head		rcu; /* eventfs_file to delete */
> -		unsigned long		is_freed; /* Freed if one of the above is set */
> +		struct list_head	del_list;
> +		struct rcu_head		rcu;
> +		unsigned long		is_freed;

This is one of the cases I disagree with kerneldoc. I mean, this isn't a
public structure (it's only in this file) so I don't expect it to be
parsed. These three fields act as one. Having them in the kerneldoc format
above makes them look as three distinct fields. Perhaps the solution is to
get rid of the starting /** so that it's no longer in kerneldoc format.

Maybe move the comments just above the union?

 	const struct file_operations	*fop;
 	const struct inode_operations	*iop;
	/*
	 * @del_list:	list of eventfs_file to delete
	 * @rcu:	eventfs_file to delete
	 * @is_freed:	Non-zero if @del_list or @rcu is active
	 */
	union {
		struct list_head	del_list;
		struct rcu_head		rcu;
		unsigned long		is_freed;
	};

-- Steve


>  	};
>  	void				*data;
>  	umode_t				mode;

Re: [PATCH] tracefs: Fix kernel-doc warnings

[Matthew Wilcox]

On Mon, Aug 21, 2023 at 10:01:46AM -0400, Steven Rostedt wrote:
> This is one of the cases I disagree with kerneldoc. I mean, this isn't a
> public structure (it's only in this file) so I don't expect it to be
> parsed. These three fields act as one. Having them in the kerneldoc format
> above makes them look as three distinct fields. Perhaps the solution is to
> get rid of the starting /** so that it's no longer in kerneldoc format.

Yes, take it out of kernel-doc's purview by removing that second *.
I don't think you need me to send a v2 patch to do that ;-)

Re: [PATCH] tracefs: Fix kernel-doc warnings

[Steven Rostedt]

On Mon, 21 Aug 2023 15:04:27 +0100
Matthew Wilcox <willy@infradead.org> wrote:

> On Mon, Aug 21, 2023 at 10:01:46AM -0400, Steven Rostedt wrote:
> > This is one of the cases I disagree with kerneldoc. I mean, this isn't a
> > public structure (it's only in this file) so I don't expect it to be
> > parsed. These three fields act as one. Having them in the kerneldoc format
> > above makes them look as three distinct fields. Perhaps the solution is to
> > get rid of the starting /** so that it's no longer in kerneldoc format.  
> 
> Yes, take it out of kernel-doc's purview by removing that second *.
> I don't think you need me to send a v2 patch to do that ;-)

Yep, I'll do it.

Thanks!

-- Steve