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

在 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 <[email protected]>
> ---
> Cc: Richard Weinberger <[email protected]>
> Cc: Zhihao Cheng <[email protected]>
> Cc: [email protected]
> 
>   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 <[email protected]>
>    */
>   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.
>    */
> .
>