From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from canpmsgout07.his.huawei.com (canpmsgout07.his.huawei.com [113.46.200.222]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C506129D281 for ; Thu, 30 Jul 2026 01:25:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=113.46.200.222 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1785374759; cv=none; b=Jg3POw9uPHcj2EglTWNd07njCeoli84OF8Iu+zovlLViBYtl48MkfwW4TMFpe0NRbf3or63L1zWRx+8fyvIFmXH1TdJp+rcor0a2LNUmKP1VgLg8dOoKdTM0Mbl3n6Akyw85wQslXRoDEuXZTrNvGJyvsgUbegPbrRYRq7aRNsA= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1785374759; c=relaxed/simple; bh=62NaQdC9r8dz1kVl9C2kN8rNo+69ZRiiAfPmddfjd6A=; h=Subject:To:CC:References:From:Message-ID:Date:MIME-Version: In-Reply-To:Content-Type; b=GUdAq0IdYaVzA27EldXFnrZfjISIy9lrbr16iwQvw1LSQSEjrbZlUsAs4ndg2LIvBFhGLgXVBzZ0QIXOAFAv6jNRKW9s3WqvF7sM28B8bovD/6V5glN9uoBTuircXHEK5ticsoQw1Uia2haLpJc14vr9h4xbNRFl//Olbdx7Q8o= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=huawei.com; spf=pass smtp.mailfrom=huawei.com; dkim=pass (1024-bit key) header.d=huawei.com header.i=@huawei.com header.b=H8SFD9A1; arc=none smtp.client-ip=113.46.200.222 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=huawei.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=huawei.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=huawei.com header.i=@huawei.com header.b="H8SFD9A1" dkim-signature: v=1; a=rsa-sha256; d=huawei.com; s=dkim; c=relaxed/relaxed; q=dns/txt; h=From; bh=PJciObAD+Ne2tLBc7/JqWnL9mRfNdvZt8+mkb7D0xlA=; b=H8SFD9A1p7yufejgWILDK6MtrgNdcWCXyVFvw/K4ErT8Ic+xalfAdHHKkBBGOaVvJaiUgLBlr sEQg2KATgYOAg37hc7/MlgBPyzKnVO0t3TD2jvZ6mLijPZ8L9NbiXPmrqfwWLB5EAkjn+M3vphw 3JUG/cQzl8jEMHtYAYAUxdk= Received: from mail.maildlp.com (unknown [172.19.163.15]) by canpmsgout07.his.huawei.com (SkyGuard) with ESMTPS id 4h9WVx1sRczLlTk; Thu, 30 Jul 2026 09:16:25 +0800 (CST) Received: from whupemo200011.china.huawei.com (unknown [7.152.185.179]) by mail.maildlp.com (Postfix) with ESMTPS id A667040578; Thu, 30 Jul 2026 09:25:52 +0800 (CST) Received: from [10.174.178.46] (10.174.178.46) by whupemo200011.china.huawei.com (7.152.185.179) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.1544.11; Thu, 30 Jul 2026 09:25:51 +0800 Subject: Re: [PATCH 3/3] ubifs: ubifs.h: clean up kernel-doc comments To: Randy Dunlap , CC: Richard Weinberger , References: <20260729172044.1793865-1-rdunlap@infradead.org> <20260729172044.1793865-4-rdunlap@infradead.org> From: Zhihao Cheng Message-ID: <4502589b-1aad-758f-dea2-023bd090fb08@huawei.com> Date: Thu, 30 Jul 2026 09:25:50 +0800 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:68.0) Gecko/20100101 Thunderbird/68.5.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 In-Reply-To: <20260729172044.1793865-4-rdunlap@infradead.org> Content-Type: text/plain; charset="gbk"; format=flowed Content-Transfer-Encoding: 8bit X-ClientProxiedBy: kwepems200002.china.huawei.com (7.221.188.68) To whupemo200011.china.huawei.com (7.152.185.179) ÔÚ 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 > --- > Cc: Richard Weinberger > Cc: Zhihao Cheng > 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 > */ > 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. > */ > . >