| Message ID | 20230818201414.2729745-1-willy@infradead.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | tracefs: Fix kernel-doc warnings | expand |
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;
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 ;-)
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
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;
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(-)