[PATCH] ubifs: headers: clean up some kernel-doc comments

[PATCH] ubifs: headers: clean up some kernel-doc comments

[Randy Dunlap]

Clean up kernel-doc comments in 3 ubifs header files:

 [PATCH 1/3] ubifs: debug.h: fix kernel-doc struct prototypes
 [PATCH 2/3] ubifs: key.h: use correct function parameter name
 [PATCH 3/3] ubifs: ubifs.h: clean up kernel-doc comments

 fs/ubifs/debug.h |    4 ++--
 fs/ubifs/key.h   |    2 +-
 fs/ubifs/ubifs.h |   20 ++++++++++++--------
 3 files changed, 15 insertions(+), 11 deletions(-)

Cc: Richard Weinberger <richard@nod.at>
Cc: Zhihao Cheng <chengzhihao1@huawei.com>
Cc: linux-mtd@lists.infradead.org

[PATCH 1/3] ubifs: debug.h: fix kernel-doc struct prototypes

[Randy Dunlap]

Use the "struct" keyword to describe structs in kernel-doc format.
This avoids kernel-doc warnings:

Warning: fs/ubifs/debug.h:75 cannot understand function prototype: 'struct ubifs_debug_info'
Warning: fs/ubifs/debug.h:130 cannot understand function prototype: 'struct ubifs_global_debug_info'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Richard Weinberger <richard@nod.at>
Cc: Zhihao Cheng <chengzhihao1@huawei.com>
Cc: linux-mtd@lists.infradead.org

 fs/ubifs/debug.h |    4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

--- linux-next-20260729.orig/fs/ubifs/debug.h
+++ linux-next-20260729/fs/ubifs/debug.h
@@ -26,7 +26,7 @@ typedef int (*dbg_znode_callback)(struct
 #define UBIFS_DFS_DIR_LEN  (3 + 1 + 2 + 3 + 1)
 
 /**
- * ubifs_debug_info - per-FS debugging information.
+ * struct ubifs_debug_info - per-FS debugging information.
  * @old_zroot: old index root - used by 'dbg_check_old_index()'
  * @old_zroot_level: old index root level - used by 'dbg_check_old_index()'
  * @old_zroot_sqnum: old index root sqnum - used by 'dbg_check_old_index()'
@@ -119,7 +119,7 @@ struct ubifs_debug_info {
 };
 
 /**
- * ubifs_global_debug_info - global (not per-FS) UBIFS debugging information.
+ * struct ubifs_global_debug_info - global (not per-FS) UBIFS debugging information.
  *
  * @chk_gen: if general extra checks are enabled
  * @chk_index: if index xtra checks are enabled

[PATCH 2/3] ubifs: key.h: use correct function parameter name

[Randy Dunlap]

Use @hash as the function parameter name to prevent kernel-doc warnings:

Warning: fs/ubifs/key.h:42 function parameter 'hash' not described in 'key_mask_hash'
Warning: fs/ubifs/key.h:42 Excess function parameter 'val' description in 'key_mask_hash'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Richard Weinberger <richard@nod.at>
Cc: Zhihao Cheng <chengzhihao1@huawei.com>
Cc: linux-mtd@lists.infradead.org

 fs/ubifs/key.h |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

--- linux-next-20260729.orig/fs/ubifs/key.h
+++ linux-next-20260729/fs/ubifs/key.h
@@ -33,7 +33,7 @@
 
 /**
  * key_mask_hash - mask a valid hash value.
- * @val: value to be masked
+ * @hash: value to be masked
  *
  * We use hash values as offset in directories, so values %0 and %1 are
  * reserved for "." and "..". %2 is reserved for "end of readdir" marker. This

[PATCH 3/3] ubifs: ubifs.h: clean up kernel-doc comments

[Randy Dunlap]

- use the struct keyword when describing a struct in kernel-doc format.
- add or correct missing struct members @leaf, @eof, and
  @superblock_need_write.
- add Returns: clauses for 4 function descriptions.

to prevent kernel-doc warnings:

Warning: fs/ubifs/ubifs.h:755 struct member 'leaf' not described in 'ubifs_zbranch'
Warning: fs/ubifs/ubifs.h:814 struct member 'eof' not described in 'bu_info'
Warning: fs/ubifs/ubifs.h:814 Excess struct member 'oef' description in 'bu_info'
Warning: fs/ubifs/ubifs.h:992 cannot understand function prototype: 'struct ubifs_stats_info'
Warning: fs/ubifs/ubifs.h:1513 struct member 'superblock_need_write' not described in 'ubifs_info'
Warning: fs/ubifs/ubifs.h:1597 No description found for return value of 'ubifs_check_hash'
Warning: fs/ubifs/ubifs.h:1612 No description found for return value of 'ubifs_check_hmac'
Warning: fs/ubifs/ubifs.h:1653 No description found for return value of 'ubifs_branch_hash'
Warning: fs/ubifs/ubifs.h:1703 No description found for return value of 'ubifs_auth_node_sz'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Richard Weinberger <richard@nod.at>
Cc: Zhihao Cheng <chengzhihao1@huawei.com>
Cc: linux-mtd@lists.infradead.org

 fs/ubifs/ubifs.h |   20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

--- linux-next-20260729.orig/fs/ubifs/ubifs.h
+++ linux-next-20260729/fs/ubifs/ubifs.h
@@ -738,6 +738,7 @@ struct ubifs_jhead {
  * struct ubifs_zbranch - key/coordinate/length branch stored in znodes.
  * @key: key
  * @znode: znode address in memory
+ * @leaf: leaf node
  * @lnum: LEB number of the target node (indexing node or data node)
  * @offs: target node offset within @lnum
  * @len: target node length
@@ -801,7 +802,7 @@ struct ubifs_znode {
  * @gc_seq: GC sequence number to detect races with GC
  * @cnt: number of data nodes for bulk read
  * @blk_cnt: number of data blocks including holes
- * @oef: end of file reached
+ * @eof: end of file reached
  */
 struct bu_info {
 	union ubifs_key key;
@@ -985,7 +986,7 @@ struct ubifs_budg_info {
 };
 
 /**
- * ubifs_stats_info - per-FS statistics information.
+ * struct ubifs_stats_info - per-FS statistics information.
  * @magic_errors: number of bad magic numbers (will be reset with a new mount).
  * @node_errors: number of bad nodes (will be reset with a new mount).
  * @crc_errors: number of bad crcs (will be reset with a new mount).
@@ -1051,6 +1052,7 @@ struct ubifs_debug_info;
  * @rw_incompat: the media is not R/W compatible
  * @assert_action: action to take when a ubifs_assert() fails
  * @authenticated: flag indigating the FS is mounted in authenticated mode
+ * @superblock_need_write: superblock node needs to be written
  *
  * @tnc_mutex: protects the Tree Node Cache (TNC), @zroot, @cnext, @enext, and
  *             @calc_idx_sz
@@ -1588,8 +1590,9 @@ int ubifs_prepare_auth_node(struct ubifs
  * @expected: first hash
  * @got: second hash
  *
- * Compare two hashes @expected and @got. Returns 0 when they are equal, a
- * negative error code otherwise.
+ * Compare two hashes @expected and @got.
+ *
+ * Returns: 0 when they are equal, a negative error code otherwise.
  */
 static inline int ubifs_check_hash(const struct ubifs_info *c,
 				   const u8 *expected, const u8 *got)
@@ -1603,8 +1606,9 @@ static inline int ubifs_check_hash(const
  * @expected: first HMAC
  * @got: second HMAC
  *
- * Compare two hashes @expected and @got. Returns 0 when they are equal, a
- * negative error code otherwise.
+ * Compare two hashes @expected and @got.
+ *
+ * Returns: 0 when they are equal, a negative error code otherwise.
  */
 static inline int ubifs_check_hmac(const struct ubifs_info *c,
 				   const u8 *expected, const u8 *got)
@@ -1644,7 +1648,7 @@ static inline void ubifs_exit_authentica
  * @c: UBIFS file-system description object
  * @br: branch to get the hash from
  *
- * This returns a pointer to the hash of a branch. Since the key already is a
+ * Returns: a pointer to the hash of a branch. Since the key already is a
  * dynamically sized object we cannot use a struct member here.
  */
 static inline u8 *ubifs_branch_hash(struct ubifs_info *c,
@@ -1694,7 +1698,7 @@ static inline int ubifs_node_verify_hmac
  * ubifs_auth_node_sz - returns the size of an authentication node
  * @c: UBIFS file-system description object
  *
- * This function returns the size of an authentication node which can
+ * Returns: the size of an authentication node which can
  * be 0 for unauthenticated filesystems or the real size of an auth node
  * authentication is enabled.
  */

Re: [PATCH 2/3] ubifs: key.h: use correct function parameter name

[Zhihao Cheng]

在 2026/7/30 1:20, Randy Dunlap 写道:
> Use @hash as the function parameter name to prevent kernel-doc warnings:
> 
> Warning: fs/ubifs/key.h:42 function parameter 'hash' not described in 'key_mask_hash'
> Warning: fs/ubifs/key.h:42 Excess function parameter 'val' description in 'key_mask_hash'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Richard Weinberger <richard@nod.at>
> Cc: Zhihao Cheng <chengzhihao1@huawei.com>
> Cc: linux-mtd@lists.infradead.org
> 
>   fs/ubifs/key.h |    2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Zhihao Cheng <chengzhihao1@huawei.com>
> 
> --- linux-next-20260729.orig/fs/ubifs/key.h
> +++ linux-next-20260729/fs/ubifs/key.h
> @@ -33,7 +33,7 @@
>   
>   /**
>    * key_mask_hash - mask a valid hash value.
> - * @val: value to be masked
> + * @hash: value to be masked
>    *
>    * We use hash values as offset in directories, so values %0 and %1 are
>    * reserved for "." and "..". %2 is reserved for "end of readdir" marker. This
> .
> 

Re: [PATCH 3/3] ubifs: ubifs.h: clean up kernel-doc comments

[Zhihao Cheng]

在 2026/7/30 1:20, Randy Dunlap 写道:
> - use the struct keyword when describing a struct in kernel-doc format.
> - add or correct missing struct members @leaf, @eof, and
>    @superblock_need_write.
> - add Returns: clauses for 4 function descriptions.
> 
> to prevent kernel-doc warnings:
> 
> Warning: fs/ubifs/ubifs.h:755 struct member 'leaf' not described in 'ubifs_zbranch'
> Warning: fs/ubifs/ubifs.h:814 struct member 'eof' not described in 'bu_info'
> Warning: fs/ubifs/ubifs.h:814 Excess struct member 'oef' description in 'bu_info'
> Warning: fs/ubifs/ubifs.h:992 cannot understand function prototype: 'struct ubifs_stats_info'
> Warning: fs/ubifs/ubifs.h:1513 struct member 'superblock_need_write' not described in 'ubifs_info'
> Warning: fs/ubifs/ubifs.h:1597 No description found for return value of 'ubifs_check_hash'
> Warning: fs/ubifs/ubifs.h:1612 No description found for return value of 'ubifs_check_hmac'
> Warning: fs/ubifs/ubifs.h:1653 No description found for return value of 'ubifs_branch_hash'
> Warning: fs/ubifs/ubifs.h:1703 No description found for return value of 'ubifs_auth_node_sz'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Richard Weinberger <richard@nod.at>
> Cc: Zhihao Cheng <chengzhihao1@huawei.com>
> Cc: linux-mtd@lists.infradead.org
> 
>   fs/ubifs/ubifs.h |   20 ++++++++++++--------
>   1 file changed, 12 insertions(+), 8 deletions(-)
> 
> --- linux-next-20260729.orig/fs/ubifs/ubifs.h
> +++ linux-next-20260729/fs/ubifs/ubifs.h
> @@ -738,6 +738,7 @@ struct ubifs_jhead {
>    * struct ubifs_zbranch - key/coordinate/length branch stored in znodes.
>    * @key: key
>    * @znode: znode address in memory
> + * @leaf: leaf node
>    * @lnum: LEB number of the target node (indexing node or data node)
>    * @offs: target node offset within @lnum
>    * @len: target node length
> @@ -801,7 +802,7 @@ struct ubifs_znode {
>    * @gc_seq: GC sequence number to detect races with GC
>    * @cnt: number of data nodes for bulk read
>    * @blk_cnt: number of data blocks including holes
> - * @oef: end of file reached
> + * @eof: end of file reached

Reviewed-by: Zhihao Cheng <chengzhihao1@huawei.com>
>    */
>   struct bu_info {
>   	union ubifs_key key;
> @@ -985,7 +986,7 @@ struct ubifs_budg_info {
>   };
>   
>   /**
> - * ubifs_stats_info - per-FS statistics information.
> + * struct ubifs_stats_info - per-FS statistics information.
>    * @magic_errors: number of bad magic numbers (will be reset with a new mount).
>    * @node_errors: number of bad nodes (will be reset with a new mount).
>    * @crc_errors: number of bad crcs (will be reset with a new mount).
> @@ -1051,6 +1052,7 @@ struct ubifs_debug_info;
>    * @rw_incompat: the media is not R/W compatible
>    * @assert_action: action to take when a ubifs_assert() fails
>    * @authenticated: flag indigating the FS is mounted in authenticated mode
> + * @superblock_need_write: superblock node needs to be written
>    *
>    * @tnc_mutex: protects the Tree Node Cache (TNC), @zroot, @cnext, @enext, and
>    *             @calc_idx_sz
> @@ -1588,8 +1590,9 @@ int ubifs_prepare_auth_node(struct ubifs
>    * @expected: first hash
>    * @got: second hash
>    *
> - * Compare two hashes @expected and @got. Returns 0 when they are equal, a
> - * negative error code otherwise.
> + * Compare two hashes @expected and @got.
> + *
> + * Returns: 0 when they are equal, a negative error code otherwise.
>    */
>   static inline int ubifs_check_hash(const struct ubifs_info *c,
>   				   const u8 *expected, const u8 *got)
> @@ -1603,8 +1606,9 @@ static inline int ubifs_check_hash(const
>    * @expected: first HMAC
>    * @got: second HMAC
>    *
> - * Compare two hashes @expected and @got. Returns 0 when they are equal, a
> - * negative error code otherwise.
> + * Compare two hashes @expected and @got.
> + *
> + * Returns: 0 when they are equal, a negative error code otherwise.
>    */
>   static inline int ubifs_check_hmac(const struct ubifs_info *c,
>   				   const u8 *expected, const u8 *got)
> @@ -1644,7 +1648,7 @@ static inline void ubifs_exit_authentica
>    * @c: UBIFS file-system description object
>    * @br: branch to get the hash from
>    *
> - * This returns a pointer to the hash of a branch. Since the key already is a
> + * Returns: a pointer to the hash of a branch. Since the key already is a
>    * dynamically sized object we cannot use a struct member here.
>    */
>   static inline u8 *ubifs_branch_hash(struct ubifs_info *c,
> @@ -1694,7 +1698,7 @@ static inline int ubifs_node_verify_hmac
>    * ubifs_auth_node_sz - returns the size of an authentication node
>    * @c: UBIFS file-system description object
>    *
> - * This function returns the size of an authentication node which can
> + * Returns: the size of an authentication node which can
>    * be 0 for unauthenticated filesystems or the real size of an auth node
>    * authentication is enabled.
>    */
> .
> 

Re: [PATCH] ubifs: headers: clean up some kernel-doc comments

[Richard Weinberger (sigma star gmbh)]

From: Richard Weinberger <richard@nod.at>


On Wed, 29 Jul 2026 10:20:41 -0700, Randy Dunlap wrote:
> Clean up kernel-doc comments in 3 ubifs header files:
> 
>  [PATCH 1/3] ubifs: debug.h: fix kernel-doc struct prototypes
>  [PATCH 2/3] ubifs: key.h: use correct function parameter name
>  [PATCH 3/3] ubifs: ubifs.h: clean up kernel-doc comments
> 
>  fs/ubifs/debug.h |    4 ++--
>  fs/ubifs/key.h   |    2 +-
>  fs/ubifs/ubifs.h |   20 ++++++++++++--------
>  3 files changed, 15 insertions(+), 11 deletions(-)
> 
> [...]

Applied, thanks!

[1/3] ubifs: debug.h: fix kernel-doc struct prototypes
      commit: f06711486c12c1fbb3ea9c0c595ca244b111891f
[2/3] ubifs: key.h: use correct function parameter name
      commit: abd6591fb5cc1490ab2cf5d9ff513a6677fa57b2
[3/3] ubifs: ubifs.h: clean up kernel-doc comments
      commit: 4e5e02340a18183b0f8ad633da1516cad92ee43e

Best regards,
-- 
Richard Weinberger <richard@nod.at>