linux-kernel - [PATCH v3 11/24] dcache: Fix docstring comment for d

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20190327051717.23225-12-tobin@kernel.org>
Date:   Wed, 27 Mar 2019 16:17:04 +1100
From:   "Tobin C. Harding" <tobin@...nel.org>
To:     Al Viro <viro@...iv.linux.org.uk>
Cc:     "Tobin C. Harding" <tobin@...nel.org>,
        Jonathan Corbet <corbet@....net>,
        Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Neil Brown <neilb@...e.com>,
        Randy Dunlap <rdunlap@...radead.org>,
        linux-doc@...r.kernel.org, linux-fsdevel@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: [PATCH v3 11/24] dcache: Fix docstring comment for d_drop()

Currently the function docstring comment for d_drop() is combined for
d_drop() and __d_drop().  Also the comment includes information on
internal function ___d_drop(), this information does not need to be
exposed via the kernel docs.

Put internal documentation in a non-docstring comment above the relevant
function (___d_drop()).

Add docstring comments to both d_drop() and __d_drop() (both are
external functions).  Make d_drop() comment very simple, pointing to
__d_drop() comment.

Signed-off-by: Tobin C. Harding <tobin@...nel.org>
---
 fs/dcache.c | 41 +++++++++++++++++++++++++++--------------
 1 file changed, 27 insertions(+), 14 deletions(-)

diff --git a/fs/dcache.c b/fs/dcache.c
index 141ffe27e95a..8094ae9c2d1b 100644
--- a/fs/dcache.c
+++ b/fs/dcache.c
@@ -429,21 +429,11 @@ static void d_lru_shrink_move(struct list_lru_one *lru, struct dentry *dentry,
 	list_lru_isolate_move(lru, &dentry->d_lru, list);
 }
 
-/**
- * d_drop - drop a dentry
- * @dentry: dentry to drop
- *
- * d_drop() unhashes the entry from the parent dentry hashes, so that it won't
- * be found through a VFS lookup any more. Note that this is different from
- * deleting the dentry - d_delete will try to mark the dentry negative if
- * possible, giving a successful _negative_ lookup, while d_drop will
- * just make the cache lookup fail.
- *
- * d_drop() is used mainly for stuff that wants to invalidate a dentry for some
- * reason (NFS timeouts or autofs deletes).
+/*
+ * ___d_drop() - Drop a dentry.
+ * @dentry: The dentry to drop.
  *
- * __d_drop requires dentry->d_lock
- * ___d_drop doesn't mark dentry as "unhashed"
+ * Does not mark dentry as "unhashed"
  *   (dentry->d_hash.pprev will be LIST_POISON2, not NULL).
  */
 static void ___d_drop(struct dentry *dentry)
@@ -464,6 +454,21 @@ static void ___d_drop(struct dentry *dentry)
 	hlist_bl_unlock(b);
 }
 
+/**
+ * __d_drop() - Drop a dentry.
+ * @dentry: The dentry to drop.
+ *
+ * Unhashes the entry from the parent dentry hashes, so that it won't
+ * be found through a VFS lookup any more. Note that this is different
+ * from deleting the dentry - d_delete() will try to mark the dentry
+ * negative if possible, giving a successful _negative_ lookup, while
+ * __d_drop() will just make the cache lookup fail.
+ *
+ * __d_drop() is used mainly for stuff that wants to invalidate a dentry
+ * for some reason (NFS timeouts or autofs deletes).
+ *
+ * Context: Caller must hold the dentry->d_lock.
+ */
 void __d_drop(struct dentry *dentry)
 {
 	if (!d_unhashed(dentry)) {
@@ -474,6 +479,14 @@ void __d_drop(struct dentry *dentry)
 }
 EXPORT_SYMBOL(__d_drop);
 
+/**
+ * d_drop() - Drop a dentry.
+ * @dentry: The dentry to drop.
+ *
+ * Wrapper around __d_drop() that handles the locking.
+ *
+ * Context: Takes/drops the dentry->d_lock.
+ */
 void d_drop(struct dentry *dentry)
 {
 	spin_lock(&dentry->d_lock);
-- 
2.21.0