[PATCH] linux/pipe_fs_i.h: fix kernel-doc warnings after @wait was split

[PATCH] linux/pipe_fs_i.h: fix kernel-doc warnings after @wait was split

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

Fix kernel-doc warnings in struct pipe_inode_info after @wait was
split into @rd_wait and @wr_wait.

../include/linux/pipe_fs_i.h:66: warning: Function parameter or member 'rd_wait' not described in 'pipe_inode_info'
../include/linux/pipe_fs_i.h:66: warning: Function parameter or member 'wr_wait' not described in 'pipe_inode_info'

Fixes: 0ddad21d3e99 ("pipe: use exclusive waits when reading or writing")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
 include/linux/pipe_fs_i.h |    3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

--- lnx-56-rc1.orig/include/linux/pipe_fs_i.h
+++ lnx-56-rc1/include/linux/pipe_fs_i.h
@@ -29,7 +29,8 @@ struct pipe_buffer {
 /**
  *	struct pipe_inode_info - a linux kernel pipe
  *	@mutex: mutex protecting the whole thing
- *	@wait: reader/writer wait point in case of empty/full pipe
+ *	@rd_wait: reader wait point in case of empty pipe
+ *	@wr_wait: writer wait point in case of full pipe
  *	@head: The point of buffer production
  *	@tail: The point of buffer consumption
  *	@max_usage: The maximum number of slots that may be used in the ring

Re: [PATCH] linux/pipe_fs_i.h: fix kernel-doc warnings after @wait was split

[Linus Torvalds]

On Sun, Feb 9, 2020 at 7:36 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
> Fix kernel-doc warnings in struct pipe_inode_info after @wait was
> split into @rd_wait and @wr_wait.

Thanks, applied.

I've considered adding some doc building to my basic tests, but it is
(a) somewhat slow and (b) has always been very noisy.

And that (b) is why I really don't do it. The reason I require the
basic build to be warning-free is that because that way any new
warnings stand out. But that's just not the case for docs.

What do you use to notice new errors? Or is there some trick to make
it less noisy?

               Linus

Re: [PATCH] linux/pipe_fs_i.h: fix kernel-doc warnings after @wait was split

[Randy Dunlap]

On 2/12/20 11:57 AM, Linus Torvalds wrote:
> On Sun, Feb 9, 2020 at 7:36 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>>
>> Fix kernel-doc warnings in struct pipe_inode_info after @wait was
>> split into @rd_wait and @wr_wait.
> 
> Thanks, applied.
> 
> I've considered adding some doc building to my basic tests, but it is
> (a) somewhat slow and (b) has always been very noisy.
> 
> And that (b) is why I really don't do it. The reason I require the
> basic build to be warning-free is that because that way any new
> warnings stand out. But that's just not the case for docs.
> 
> What do you use to notice new errors? Or is there some trick to make
> it less noisy?

It's awfully noisy.  I just do lots of "grep -v" to ignore some messages
that are always there and then I manually ignore lots of others that are
not new.  Very little automation.  No magic tricks.

-- 
~Randy

Re: [PATCH] linux/pipe_fs_i.h: fix kernel-doc warnings after @wait was split

[Jonathan Corbet]

On Wed, 12 Feb 2020 11:57:39 -0800
Linus Torvalds <torvalds@linux-foundation.org> wrote:

> I've considered adding some doc building to my basic tests, but it is
> (a) somewhat slow and (b) has always been very noisy.
> 
> And that (b) is why I really don't do it. The reason I require the
> basic build to be warning-free is that because that way any new
> warnings stand out. But that's just not the case for docs.
> 
> What do you use to notice new errors? Or is there some trick to make
> it less noisy?

I save the output and do a diff ... not the greatest workflow.

The docs-build warnings are a huge problem, which is why getting rid of
them is at the top of my priority list.  It's a fairly lonely game of
whack-a-mole at the moment, though.

Once we're there, it should be pretty easy to add a quick check that
doesn't actually build the docs and, thus, isn't so painfully slow.  But
that won't really be useful until we can get the build clean.

jon