From: Dominique Martinet <asmadeus@codewreck.org>
To: David Howells <dhowells@redhat.com>,
Matthew Wilcox <willy@infradead.org>
Cc: linux-fsdevel@vger.kernel.org, Jeff Layton <jlayton@kernel.org>,
Marc Dionne <marc.dionne@auristor.com>,
Steve French <sfrench@samba.org>,
Trond Myklebust <trond.myklebust@hammerspace.com>,
Anna Schumaker <anna.schumaker@netapp.com>,
Mauro Carvalho Chehab <mchehab@kernel.org>,
v9fs-developer@lists.sourceforge.net,
linux-afs@lists.infradead.org, linux-cifs@vger.kernel.org,
linux-nfs@vger.kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: Re: [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1
Date: Mon, 20 Sep 2021 22:02:55 +0900 [thread overview]
Message-ID: <YUiGf9bzSX62jUrP@codewreck.org> (raw)
In-Reply-To: <YUiAmnMV7+fprNC1@casper.infradead.org> <163214005516.2945267.7000234432243167892.stgit@warthog.procyon.org.uk>
David Howells wrote on Mon, Sep 20, 2021 at 01:14:15PM +0100:
> Deal with some warnings generated from make W=1:
>
> (1) Add/remove/fix kerneldoc parameters descriptions.
>
> (2) afs_sillyrename() isn't an API functions, so remove the kerneldoc
> annotation.
>
> (3) The fscache object CREATE_OBJECT work state isn't used, so remove it.
>
> (4) Move __add_fid() from between v9fs_fid_add() and its comment.
>
> (5) 9p's caches_show() doesn't really make sense as an API function, show
> remove the kerneldoc annotation. It's also not prefixed with 'v9fs_'.
Happy with the 9p changes:
Reviewed-by: Dominique Martinet <asmadeus@codewreck.org>
Having all of these in a single commit makes it difficult to deal but I
don't expect any conflict on my end, so happy to have it go in your
fscache tree.
Matthew Wilcox wrote on Mon, Sep 20, 2021 at 01:37:46PM +0100:
> This is an example of a weird pattern in filesystems. Several of
> them have kernel-doc for the implementation of various ->ops methods.
> I don't necessarily believe we should delete the comments (although is
> there any useful information in the above?), but I don't see the point
> in the comment being kernel-doc.
As far as I'm concerned this is just an "it's always been like this"
thing for me/9p, I wouldn't mind if it were all converted to normal
comments -- but now it's describing arguments by name having it as
kerneldoc has helped catch comments which didn't get updated when
function changed quite a few times in patches similar to this one so it
would only make sense if we remove obvious argument descriptions as well
in my opinion, and that's a bit of manual work.
--
Dominique
next prev parent reply other threads:[~2021-09-20 13:03 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-20 12:14 [RFC PATCH] fscache, 9p, afs, cifs, nfs: Deal with some warnings from W=1 David Howells
2021-09-20 12:37 ` Matthew Wilcox
2021-09-20 12:47 ` David Howells
2021-09-20 13:02 ` Dominique Martinet [this message]
2021-09-20 17:59 ` Steve French
2021-09-20 18:16 ` David Howells
2021-09-23 19:08 ` Fwd: " Steve French
2021-09-28 8:46 ` David Howells
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=YUiGf9bzSX62jUrP@codewreck.org \
--to=asmadeus@codewreck.org \
--cc=anna.schumaker@netapp.com \
--cc=dhowells@redhat.com \
--cc=jlayton@kernel.org \
--cc=linux-afs@lists.infradead.org \
--cc=linux-cifs@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-nfs@vger.kernel.org \
--cc=marc.dionne@auristor.com \
--cc=mchehab@kernel.org \
--cc=sfrench@samba.org \
--cc=trond.myklebust@hammerspace.com \
--cc=v9fs-developer@lists.sourceforge.net \
--cc=willy@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).