diff --git a/fs/dcache.c b/fs/dcache.c
index e513a9e9e418..7acf94290b66 100644
--- a/fs/dcache.c
+++ b/fs/dcache.c
@@ -812,8 +812,8 @@ static inline bool fast_dput(struct dentry *dentry)
  * Real recursion would eat up our stack space.
  */
 
-/*
- * dput - release a dentry
+/**
+ * dput() - Release a dentry.
  * @dentry: dentry to release
  *
  * Release a dentry. This will drop the usage count and if appropriate
@@ -909,11 +909,13 @@ static struct dentry * __d_find_any_alias(struct inode *inode)
 }
 
 /**
- * d_find_any_alias - find any alias for a given inode
+ * d_find_any_alias() - Find any alias for a given inode.
  * @inode: inode to find an alias for
  *
  * If any aliases exist for the given inode, take and return a
- * reference for one of them.  If no aliases exist, return %NULL.
+ * reference for one of them.
+ *
+ * Return: The found dentry reference or %NULL if no aliases exists.
  */
 struct dentry *d_find_any_alias(struct inode *inode)
 {
@@ -926,20 +928,6 @@ struct dentry *d_find_any_alias(struct inode *inode)
 }
 EXPORT_SYMBOL(d_find_any_alias);
 
-/**
- * d_find_alias - grab a hashed alias of inode
- * @inode: inode in question
- *
- * If inode has a hashed alias, or is a directory and has any alias,
- * acquire the reference to alias and return it. Otherwise return NULL.
- * Notice that if inode is a directory there can be only one alias and
- * it can be unhashed only if it has no children, or if it is the root
- * of a filesystem, or if the directory was renamed and d_revalidate
- * was the first vfs operation to notice.
- *
- * If the inode has an IS_ROOT, DCACHE_DISCONNECTED alias, then prefer
- * any other hashed alias over that one.
- */
 static struct dentry *__d_find_alias(struct inode *inode)
 {
 	struct dentry *alias;
@@ -959,6 +947,23 @@ static struct dentry *__d_find_alias(struct inode *inode)
 	return NULL;
 }
 
+/**
+ * d_find_alias() - Grab a hashed alias of inode.
+ * @inode: inode in question
+ *
+ * If inode has a hashed alias, or is a directory and has any alias,
+ * acquire the reference to alias.  Notice that if inode is a directory
+ * there can be only one alias and it can be unhashed only if it has no
+ * children, or if it is the root of a filesystem, or if the directory
+ * was renamed and d_revalidate was the first vfs operation to notice.
+ *
+ * If the inode has an IS_ROOT, DCACHE_DISCONNECTED alias, then prefer
+ * any other hashed alias over that one.
+ *
+ * Context: Takes the inode->i_lock and the dentry->d_lock for each
+ *          alias i.e. for each inode->i_dentry.
+ * Return: The found dentry reference or %NULL if no alias found.
+ */
 struct dentry *d_find_alias(struct inode *inode)
 {
 	struct dentry *de = NULL;
@@ -972,9 +977,11 @@ struct dentry *d_find_alias(struct inode *inode)
 }
 EXPORT_SYMBOL(d_find_alias);
 
-/*
- *	Try to kill dentries associated with this inode.
- * WARNING: you must own a reference to inode.
+/**
+ * d_prune_aliases() - Try to kill dentries associated with this inode.
+ * @inode: The inode we are working on.
+ *
+ * Context: Caller must own a reference to inode.
  */
 void d_prune_aliases(struct inode *inode)
 {
@@ -1148,7 +1155,7 @@ static enum lru_status dentry_lru_isolate(struct list_head *item,
 }
 
 /**
- * prune_dcache_sb - shrink the dcache
+ * prune_dcache_sb() - Shrink the dcache.
  * @sb: superblock
  * @sc: shrink control, passed to list_lru_shrink_walk()
  *
@@ -1158,6 +1165,8 @@ static enum lru_status dentry_lru_isolate(struct list_head *item,
  *
  * This function may fail to free any resources if all the dentries are in
  * use.
+ *
+ * Return: The number of dentries freed.
  */
 long prune_dcache_sb(struct super_block *sb, struct shrink_control *sc)
 {
@@ -1192,7 +1201,7 @@ static enum lru_status dentry_lru_isolate_shrink(struct list_head *item,
 
 
 /**
- * shrink_dcache_sb - shrink dcache for a superblock
+ * shrink_dcache_sb() - Shrink dcache for a superblock.
  * @sb: superblock
  *
  * Shrink the dcache for the specified super block. This is used to free
@@ -1229,10 +1238,10 @@ enum d_walk_ret {
 };
 
 /**
- * d_walk - walk the dentry tree
- * @parent:	start of walk
- * @data:	data passed to @enter() and @finish()
- * @enter:	callback when first entering the dentry
+ * d_walk() - Walk the dentry tree.
+ * @parent: Start of walk.
+ * @data: Data passed to @enter() and @finish().
+ * @enter: Callback when first entering the dentry.
  *
  * The @enter() callbacks are called with d_lock held.
  */
@@ -1362,12 +1371,11 @@ static enum d_walk_ret path_check_mount(void *data, struct dentry *dentry)
 }
 
 /**
- * path_has_submounts - check for mounts over a dentry in the
- *                      current namespace.
+ * path_has_submounts() - Check current namespace for mounts over a dentry.
  * @parent: path to check.
  *
- * Return true if the parent or its subdirectories contain
- * a mount point in the current namespace.
+ * Return: True if the parent or its subdirectories contain
+ *         a mount point in the current namespace.
  */
 int path_has_submounts(const struct path *parent)
 {
@@ -1381,13 +1389,17 @@ int path_has_submounts(const struct path *parent)
 }
 EXPORT_SYMBOL(path_has_submounts);
 
-/*
+/**
+ * d_set_mounted() - Set a mountpoint.
+ * @dentry: The dentry we are working on.
+ *
  * Called by mount code to set a mountpoint and check if the mountpoint is
  * reachable (e.g. NFS can unhash a directory dentry and then the complete
  * subtree can become unreachable).
  *
- * Only one of d_invalidate() and d_set_mounted() must succeed.  For
- * this reason take rename_lock and d_lock on dentry and ancestors.
+ * Only one of d_invalidate() and d_set_mounted() must succeed.
+ *
+ * Context: Take rename_lock and d_lock on dentry and ancestors.
  */
 int d_set_mounted(struct dentry *dentry)
 {
@@ -1468,7 +1480,7 @@ static enum d_walk_ret select_collect(void *_data, struct dentry *dentry)
 }
 
 /**
- * shrink_dcache_parent - prune dcache
+ * shrink_dcache_parent() - Prune dcache.
  * @parent: parent of entries to prune
  *
  * Prune the dcache to remove unused children of the parent dentry.
@@ -1527,8 +1539,13 @@ static void do_one_tree(struct dentry *dentry)
 	dput(dentry);
 }
 
-/*
- * destroy the dentries attached to a superblock on unmounting
+/**
+ * shrink_dcache_for_umount() - Destroy the dentries attached to a superblock.
+ * @sb: The superblock to shrink.
+ *
+ * Used when unmounting.  Shrinks (removes unused dentries) the sb root
+ * node then verifies tree does not contain any inuse dentries.  Printks
+ * a error message if any dentry is still inuse.
  */
 void shrink_dcache_for_umount(struct super_block *sb)
 {
@@ -1558,7 +1575,7 @@ static enum d_walk_ret find_submount(void *_data, struct dentry *dentry)
 }
 
 /**
- * d_invalidate - detach submounts, prune dcache, and drop
+ * d_invalidate() - Detach submounts, prune dcache, and drop.
  * @dentry: dentry to invalidate (aka detach, prune and drop)
  */
 void d_invalidate(struct dentry *dentry)
@@ -1593,15 +1610,15 @@ void d_invalidate(struct dentry *dentry)
 EXPORT_SYMBOL(d_invalidate);
 
 /**
- * __d_alloc	-	allocate a dcache entry
+ * __d_alloc() - Allocate a dcache entry.
  * @sb: filesystem it will belong to
  * @name: qstr of the name
  *
- * Allocates a dentry. It returns %NULL if there is insufficient memory
- * available. On a success the dentry is returned. The name passed in is
- * copied and the copy passed in may be reused after this call.
+ * @name is copied and may be reused after this call.
+ *
+ * Return: The newly allocated dentry on success. %NULL if there is
+ *         insufficient memory available or d_init() method fails.
  */
-
 struct dentry *__d_alloc(struct super_block *sb, const struct qstr *name)
 {
 	struct dentry *dentry;
@@ -1677,13 +1694,16 @@ struct dentry *__d_alloc(struct super_block *sb, const struct qstr *name)
 }
 
 /**
- * d_alloc	-	allocate a dcache entry
+ * d_alloc() - Allocate a dcache entry.
  * @parent: parent of entry to allocate
  * @name: qstr of the name
  *
- * Allocates a dentry. It returns %NULL if there is insufficient memory
- * available. On a success the dentry is returned. The name passed in is
- * copied and the copy passed in may be reused after this call.
+ * Allocates a dentry and adds it to @parent.  See __d_alloc() for full
+ * explanation of behaviour.
+ *
+ * @name is copied and may be reused after this call.
+ *
+ * Return: The newly allocated dentry or %NULL if __d_alloc() fails.
  */
 struct dentry *d_alloc(struct dentry * parent, const struct qstr *name)
 {
@@ -1722,7 +1742,7 @@ struct dentry *d_alloc_cursor(struct dentry * parent)
 }
 
 /**
- * d_alloc_pseudo - allocate a dentry (for lookup-less filesystems)
+ * d_alloc_pseudo() - Allocate a dentry (for lookup-less filesystems).
  * @sb: the superblock
  * @name: qstr of the name
  *
@@ -1735,6 +1755,16 @@ struct dentry *d_alloc_pseudo(struct super_block *sb, const struct qstr *name)
 }
 EXPORT_SYMBOL(d_alloc_pseudo);
 
+/**
+ * d_alloc_name() - Allocate a dcache entry.
+ * @parent: The parent of entry to allocate.
+ * @name: The name to use in the allocation.
+ *
+ * Creates a qstring from @name then allocates a dentry, adding it to
+ * @parent.  See __d_alloc() for full explanation of behaviour.
+ *
+ * Return: The newly allocated dentry or %NULL if d_alloc() fails.
+ */
 struct dentry *d_alloc_name(struct dentry *parent, const char *name)
 {
 	struct qstr q;
@@ -1775,13 +1805,13 @@ void d_set_d_op(struct dentry *dentry, const struct dentry_operations *op)
 }
 EXPORT_SYMBOL(d_set_d_op);
 
-
-/*
- * d_set_fallthru - Mark a dentry as falling through to a lower layer
- * @dentry - The dentry to mark
+/**
+ * d_set_fallthru() - Mark a dentry as falling through to a lower layer.
+ * @dentry: The dentry to mark.
  *
- * Mark a dentry as falling through to the lower layer (as set with
- * d_pin_lower()).  This flag may be recorded on the medium.
+ * Mark the dentry->d_flags to indicate that @dentry is falling through
+ * to the lower layer (as set with d_pin_lower()).  This flag may be
+ * recorded on the medium.
  */
 void d_set_fallthru(struct dentry *dentry)
 {
@@ -1841,12 +1871,10 @@ static void __d_instantiate(struct dentry *dentry, struct inode *inode)
 }
 
 /**
- * d_instantiate - fill in inode information for a dentry
+ * d_instantiate() - Fill in inode information for a dentry.
  * @entry: dentry to complete
  * @inode: inode to attach to this dentry
  *
- * Fill in inode information in the entry.
- *
  * This turns negative dentries into productive full members
  * of society.
  *
@@ -1854,7 +1882,6 @@ static void __d_instantiate(struct dentry *dentry, struct inode *inode)
  * (or otherwise set) by the caller to indicate that it is now
  * in use by the dcache.
  */
-
 void d_instantiate(struct dentry *entry, struct inode * inode)
 {
 	BUG_ON(!hlist_unhashed(&entry->d_u.d_alias));
@@ -1867,7 +1894,11 @@ void d_instantiate(struct dentry *entry, struct inode * inode)
 }
 EXPORT_SYMBOL(d_instantiate);
 
-/*
+/**
+ * d_instantiate_new() - Instantiate dentry and unlock inode.
+ * @entry: The dentry to complete.
+ * @inode: The inode to attach to this dentry.
+ *
  * This should be equivalent to d_instantiate() + unlock_new_inode(),
  * with lockdep-related part of unlock_new_inode() done before
  * anything else.  Use that instead of open-coding d_instantiate()/
@@ -1980,7 +2011,7 @@ static struct dentry *__d_obtain_alias(struct inode *inode, bool disconnected)
 }
 
 /**
- * d_obtain_alias - find or allocate a DISCONNECTED dentry for a given inode
+ * d_obtain_alias() - Find or allocate a DISCONNECTED dentry.
  * @inode: inode to allocate the dentry for
  *
  * Obtain a dentry for an inode resulting from NFS filehandle conversion or
@@ -2004,7 +2035,7 @@ struct dentry *d_obtain_alias(struct inode *inode)
 EXPORT_SYMBOL(d_obtain_alias);
 
 /**
- * d_obtain_root - find or allocate a dentry for a given inode
+ * d_obtain_root() - Find or allocate a dentry for a given inode.
  * @inode: inode to allocate the dentry for
  *
  * Obtain an IS_ROOT dentry for the root of a filesystem.
@@ -2025,7 +2056,7 @@ struct dentry *d_obtain_root(struct inode *inode)
 EXPORT_SYMBOL(d_obtain_root);
 
 /**
- * d_add_ci - lookup or allocate new dentry with case-exact name
+ * d_add_ci() - Lookup or allocate new dentry with case-exact name.
  * @inode:  the inode case-insensitive lookup has found
  * @dentry: the negative dentry that was passed to the parent's lookup func
  * @name:   the case-exact name to be associated with the returned dentry
@@ -2093,11 +2124,10 @@ static inline bool d_same_name(const struct dentry *dentry,
 }
 
 /**
- * __d_lookup_rcu - search for a dentry (racy, store-free)
+ * __d_lookup_rcu() - Search for a dentry (racy, store-free).
  * @parent: parent dentry
  * @name: qstr of name we wish to find
  * @seqp: returns d_seq value at the point where the dentry was found
- * Returns: dentry, or NULL
  *
  * __d_lookup_rcu is the dcache lookup function for rcu-walk name
  * resolution (store-free path walking) design described in
@@ -2105,21 +2135,25 @@ static inline bool d_same_name(const struct dentry *dentry,
  *
  * This is not to be used outside core vfs.
  *
- * __d_lookup_rcu must only be used in rcu-walk mode, ie. with vfsmount lock
- * held, and rcu_read_lock held. The returned dentry must not be stored into
- * without taking d_lock and checking d_seq sequence count against @seq
- * returned here.
+ * __d_lookup_rcu() must only be used in rcu-walk mode, i.e. with
+ * vfsmount lock held, and rcu_read_lock() held. The returned dentry
+ * must not be stored into without taking d_lock and checking d_seq
+ * sequence count against @seq returned here.
  *
- * A refcount may be taken on the found dentry with the d_rcu_to_refcount
- * function.
+ * A refcount may be taken on the found dentry with the
+ * d_rcu_to_refcount() function.
+ *
+ * Alternatively, __d_lookup_rcu() may be called again to look up the
+ * child of the returned dentry, so long as its parent's seqlock is
+ * checked after the child is looked up. Thus, an interlocking stepping
+ * of sequence lock checks is formed, giving integrity down the path
+ * walk.
  *
- * Alternatively, __d_lookup_rcu may be called again to look up the child of
- * the returned dentry, so long as its parent's seqlock is checked after the
- * child is looked up. Thus, an interlocking stepping of sequence lock checks
- * is formed, giving integrity down the path walk.
+ * NOTE! The caller *has* to check the resulting dentry against the
+ * sequence number we've returned before using any of the resulting
+ * dentry state!
  *
- * NOTE! The caller *has* to check the resulting dentry against the sequence
- * number we've returned before using any of the resulting dentry state!
+ * Return: dentry, or %NULL.
  */
 struct dentry *__d_lookup_rcu(const struct dentry *parent,
 				const struct qstr *name,
@@ -2206,15 +2240,16 @@ struct dentry *__d_lookup_rcu(const struct dentry *parent,
 }
 
 /**
- * d_lookup - search for a dentry
+ * d_lookup() - Search for a dentry.
  * @parent: parent dentry
  * @name: qstr of name we wish to find
- * Returns: dentry, or NULL
  *
- * d_lookup searches the children of the parent dentry for the name in
+ * d_lookup() searches the children of the parent dentry for the name in
  * question. If the dentry is found its reference count is incremented and the
  * dentry is returned. The caller must use dput to free the entry when it has
- * finished using it. %NULL is returned if the dentry does not exist.
+ * finished using it.
+ *
+ * Return: dentry, or %NULL if the dentry does not exist.
  */
 struct dentry *d_lookup(const struct dentry *parent, const struct qstr *name)
 {
@@ -2232,19 +2267,20 @@ struct dentry *d_lookup(const struct dentry *parent, const struct qstr *name)
 EXPORT_SYMBOL(d_lookup);
 
 /**
- * __d_lookup - search for a dentry (racy)
+ * __d_lookup() - Search for a dentry (racy).
  * @parent: parent dentry
  * @name: qstr of name we wish to find
- * Returns: dentry, or NULL
  *
- * __d_lookup is like d_lookup, however it may (rarely) return a
+ * __d_lookup() is like d_lookup(), however it may (rarely) return a
  * false-negative result due to unrelated rename activity.
  *
- * __d_lookup is slightly faster by avoiding rename_lock read seqlock,
- * however it must be used carefully, e.g. with a following d_lookup in
+ * __d_lookup() is slightly faster by avoiding rename_lock read seqlock,
+ * however it must be used carefully, e.g. with a following d_lookup() in
  * the case of failure.
  *
- * __d_lookup callers must be commented.
+ * __d_lookup() callers must be commented.
+ *
+ * Return: dentry, or %NULL.
  */
 struct dentry *__d_lookup(const struct dentry *parent, const struct qstr *name)
 {
@@ -2303,11 +2339,12 @@ struct dentry *__d_lookup(const struct dentry *parent, const struct qstr *name)
 }
 
 /**
- * d_hash_and_lookup - hash the qstr then search for a dentry
+ * d_hash_and_lookup() - Hash the qstr then search for a dentry.
  * @dir: Directory to search in
  * @name: qstr of name we wish to find
  *
- * On lookup failure NULL is returned; on bad name - ERR_PTR(-error)
+ * Return: The dentry if found, %NULL on lookup failure, ERR_PTR(-error)
+ *         on bad name.
  */
 struct dentry *d_hash_and_lookup(struct dentry *dir, struct qstr *name)
 {
@@ -2340,13 +2377,12 @@ EXPORT_SYMBOL(d_hash_and_lookup);
  */
 
 /**
- * d_delete - delete a dentry
+ * d_delete() - Delete a dentry.
  * @dentry: The dentry to delete
  *
  * Turn the dentry into a negative dentry if possible, otherwise
- * remove it from the hash queues so it can be deleted later
+ * remove it from the hash queues so it can be deleted later.
  */
-
 void d_delete(struct dentry * dentry)
 {
 	struct inode *inode = dentry->d_inode;
@@ -2379,7 +2415,7 @@ static void __d_rehash(struct dentry *entry)
 }
 
 /**
- * d_rehash	- add an entry back to the hash
+ * d_rehash() - Add an entry back to the hash.
  * @entry: dentry to add to the hash
  *
  * Adds a dentry to the hash according to its name.
@@ -2576,7 +2612,7 @@ static inline void __d_add(struct dentry *dentry, struct inode *inode)
 }
 
 /**
- * d_add - add dentry to hash queues
+ * d_add() - Add dentry to hash queues.
  * @entry: dentry to add
  * @inode: The inode to attach to this dentry
  *
@@ -2595,15 +2631,13 @@ void d_add(struct dentry *entry, struct inode *inode)
 EXPORT_SYMBOL(d_add);
 
 /**
- * d_exact_alias - find and hash an exact unhashed alias
+ * d_exact_alias() - Find and hash an exact unhashed alias.
  * @entry: dentry to add
  * @inode: The inode to go with this dentry
  *
- * If an unhashed dentry with the same name/parent and desired
- * inode already exists, hash and return it.  Otherwise, return
- * NULL.
- *
- * Parent directory should be locked.
+ * Context: Parent directory should be locked.
+ * Return: If an unhashed dentry with the same name/parent and desired
+ *         inode already exists, hash and return it.  Otherwise %NULL.
  */
 struct dentry *d_exact_alias(struct dentry *entry, struct inode *inode)
 {
@@ -2702,15 +2736,17 @@ static void copy_name(struct dentry *dentry, struct dentry *target)
 }
 
 /*
- * __d_move - move a dentry
+ * __d_move() - Move a dentry.
  * @dentry: entry to move
  * @target: new dentry
  * @exchange: exchange the two dentries
  *
  * Update the dcache to reflect the move of a file name. Negative
- * dcache entries should not be moved in this way. Caller must hold
- * rename_lock, the i_mutex of the source and target directories,
- * and the sb->s_vfs_rename_mutex if they differ. See lock_rename().
+ * dcache entries should not be moved in this way.
+ *
+ * Context: Caller must hold rename_lock, the i_mutex of the source and
+ *          target directories, and the sb->s_vfs_rename_mutex if they
+ *          differ. See lock_rename().
  */
 static void __d_move(struct dentry *dentry, struct dentry *target,
 		     bool exchange)
@@ -2793,14 +2829,17 @@ static void __d_move(struct dentry *dentry, struct dentry *target,
 	spin_unlock(&dentry->d_lock);
 }
 
-/*
- * d_move - move a dentry
+/**
+ * d_move() - Move a dentry.
  * @dentry: entry to move
  * @target: new dentry
  *
  * Update the dcache to reflect the move of a file name. Negative
- * dcache entries should not be moved in this way. See the locking
- * requirements for __d_move.
+ * dcache entries should not be moved in this way.
+ *
+ * Context: Caller must hold rename_lock, the i_mutex of the source and
+ *          target directories, and the sb->s_vfs_rename_mutex if they
+ *          differ. See lock_rename().
  */
 void d_move(struct dentry *dentry, struct dentry *target)
 {
@@ -2810,8 +2849,8 @@ void d_move(struct dentry *dentry, struct dentry *target)
 }
 EXPORT_SYMBOL(d_move);
 
-/*
- * d_exchange - exchange two dentries
+/**
+ * d_exchange() - Exchange two dentries.
  * @dentry1: first dentry
  * @dentry2: second dentry
  */
@@ -2830,12 +2869,12 @@ void d_exchange(struct dentry *dentry1, struct dentry *dentry2)
 }
 
 /**
- * d_ancestor - search for an ancestor
+ * d_ancestor() - Search for an ancestor.
  * @p1: ancestor dentry
  * @p2: child dentry
  *
- * Returns the ancestor dentry of p2 which is a child of p1, if p1 is
- * an ancestor of p2, else NULL.
+ * Return: The ancestor dentry of p2 which is a child of p1, if p1 is
+ *         an ancestor of p2, else %NULL.
  */
 struct dentry *d_ancestor(struct dentry *p1, struct dentry *p2)
 {
@@ -2887,13 +2926,13 @@ static int __d_unalias(struct inode *inode,
 }
 
 /**
- * d_splice_alias - splice a disconnected dentry into the tree if one exists
+ * d_splice_alias() - Splice a disconnected dentry into the tree if one exists.
  * @inode:  the inode which may have a disconnected dentry
  * @dentry: a negative dentry which we want to point to the inode.
  *
- * If inode is a directory and has an IS_ROOT alias, then d_move that in
- * place of the given dentry and return it, else simply d_add the inode
- * to the dentry and return NULL.
+ * If inode is a directory and has an IS_ROOT alias, then d_move() that in
+ * place of the given dentry and return it, else simply d_add() the inode
+ * to the dentry and return %NULL.
  *
  * If a non-IS_ROOT directory is found, the filesystem is corrupt, and
  * we should error out: directories can't have multiple aliases.
@@ -2901,7 +2940,7 @@ static int __d_unalias(struct inode *inode,
  * This is needed in the lookup routine of any filesystem that is exportable
  * (via knfsd) so that we can build dcache paths to directories effectively.
  *
- * If a dentry was found and moved, then it is returned.  Otherwise NULL
+ * If a dentry was found and moved, then it is returned.  Otherwise %NULL
  * is returned.  This matches the expected return value of ->lookup.
  *
  * Cluster filesystems may call this function with a negative, hashed dentry.
@@ -2971,11 +3010,11 @@ EXPORT_SYMBOL(d_splice_alias);
  * @new_dentry: new dentry
  * @old_dentry: old dentry
  *
- * Returns true if new_dentry is a subdirectory of the parent (at any depth).
- * Returns false otherwise.
- * Caller must ensure that "new_dentry" is pinned before calling is_subdir()
+ * Return: True if new_dentry is a subdirectory of the parent (at any
+ *         depth).  False otherwise.
+ * Context: Caller must ensure that "new_dentry" is pinned before
+ *          calling is_subdir().
  */
-
 bool is_subdir(struct dentry *new_dentry, struct dentry *old_dentry)
 {
 	bool result;
diff --git a/include/linux/dcache.h b/include/linux/dcache.h
index 862aefe5a10a..0643c5127e1a 100644
--- a/include/linux/dcache.h
+++ b/include/linux/dcache.h
@@ -296,12 +296,14 @@ extern char *dentry_path(struct dentry *, char *, int);
 /* Allocation counts.. */
 
 /**
- *	dget, dget_dlock -	get a reference to a dentry
- *	@dentry: dentry to get a reference to
+ * dget_dlock() - Get a reference to a dentry.
+ * @dentry: The dentry to get a reference to.
  *
- *	Given a dentry or %NULL pointer increment the reference count
- *	if appropriate and return the dentry. A dentry will not be
- *	destroyed when it has references.
+ * Given a dentry or %NULL pointer increment the reference count if
+ * appropriate. A dentry will not be destroyed when it has references.
+ *
+ * Context: Caller must hold the dentry->d_lock.
+ * Return: The dentry.
  */
 static inline struct dentry *dget_dlock(struct dentry *dentry)
 {
@@ -310,6 +312,16 @@ static inline struct dentry *dget_dlock(struct dentry *dentry)
 	return dentry;
 }
 
+/**
+ * dget() - Get a reference to a dentry.
+ * @dentry: The dentry to get a reference to.
+ *
+ * Given a dentry or %NULL pointer increment the reference count if
+ * appropriate. A dentry will not be destroyed when it has references.
+ *
+ * Context: Takes the dentry->d_lock.
+ * Return: The dentry.
+ */
 static inline struct dentry *dget(struct dentry *dentry)
 {
 	if (dentry)
@@ -320,12 +332,11 @@ static inline struct dentry *dget(struct dentry *dentry)
 extern struct dentry *dget_parent(struct dentry *dentry);
 
 /**
- *	d_unhashed -	is dentry hashed
- *	@dentry: entry to check
+ * d_unhashed() - Is dentry unhashed.
+ * @dentry: The dentry to check.
  *
- *	Returns true if the dentry passed is not currently hashed.
+ * Return: True if the dentry passed is not currently hashed.
  */
-
 static inline int d_unhashed(const struct dentry *dentry)
 {
 	return hlist_bl_unhashed(&dentry->d_hash);
@@ -499,7 +510,7 @@ static inline unsigned long vfs_pressure_ratio(unsigned long val)
 }
 
 /**
- * d_inode - Get the actual inode of this dentry
+ * d_inode() - Get the actual inode of this dentry.
  * @dentry: The dentry to query
  *
  * This is the helper normal filesystems should use to get at their own inodes
@@ -511,7 +522,7 @@ static inline struct inode *d_inode(const struct dentry *dentry)
 }
 
 /**
- * d_inode_rcu - Get the actual inode of this dentry with READ_ONCE()
+ * d_inode_rcu() - Get the actual inode of this dentry with READ_ONCE().
  * @dentry: The dentry to query
  *
  * This is the helper normal filesystems should use to get at their own inodes
@@ -523,7 +534,7 @@ static inline struct inode *d_inode_rcu(const struct dentry *dentry)
 }
 
 /**
- * d_backing_inode - Get upper or lower inode we should be using
+ * d_backing_inode() - Get upper or lower inode we should be using.
  * @upper: The upper layer
  *
  * This is the helper that should be used to get at the inode that will be used
@@ -540,7 +551,7 @@ static inline struct inode *d_backing_inode(const struct dentry *upper)
 }
 
 /**
- * d_backing_dentry - Get upper or lower dentry we should be using
+ * d_backing_dentry() - Get upper or lower dentry we should be using.
  * @upper: The upper layer
  *
  * This is the helper that should be used to get the dentry of the inode that
@@ -555,9 +566,9 @@ static inline struct dentry *d_backing_dentry(struct dentry *upper)
 }
 
 /**
- * d_real - Return the real dentry
+ * d_real() - Return the real dentry.
  * @dentry: the dentry to query
- * @inode: inode to select the dentry from multiple layers (can be NULL)
+ * @inode: inode to select the dentry from multiple layers (can be %NULL)
  *
  * If dentry is on a union/overlay, then return the underlying, real dentry.
  * Otherwise return the dentry itself.
@@ -574,7 +585,7 @@ static inline struct dentry *d_real(struct dentry *dentry,
 }
 
 /**
- * d_real_inode - Return the real inode
+ * d_real_inode() - Return the real inode.
  * @dentry: The dentry to query
  *
  * If dentry is on a union/overlay, then return the underlying, real inode.
