linux-next: build warning after merge of the libcrypto tree

linux-next: build warning after merge of the libcrypto tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 472 bytes --]

Hi all,

After merging the libcrypto tree, today's linux-next build (htmldocs)
produced this warning:

WARNING: /home/sfr/kernels/next/next/include/crypto/sha3.h:74 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Zeroize a sha3_ctx.  This is already called by sha3_final().  Call this

Introduced by commit

  58873ecf091b ("lib/crypto: sha3: Add SHA-3 support")

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: build warning after merge of the libcrypto tree

[Eric Biggers]

On Thu, Nov 06, 2025 at 02:36:23PM +1100, Stephen Rothwell wrote:
> Hi all,
> 
> After merging the libcrypto tree, today's linux-next build (htmldocs)
> produced this warning:
> 
> WARNING: /home/sfr/kernels/next/next/include/crypto/sha3.h:74 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Zeroize a sha3_ctx.  This is already called by sha3_final().  Call this
> 
> Introduced by commit
> 
>   58873ecf091b ("lib/crypto: sha3: Add SHA-3 support")

Thanks.  Do you know if there's an easy way to find these ahead of time?
I usually run './scripts/kernel-doc -v -none ${filename}' to catch
kerneldoc issues.  I did run it on include/crypto/sha3.h, but for some
reason it doesn't detect this issue.

'make htmldocs' doesn't find it either, but does generate a bunch of
unrelated warnings.  I may be missing an option to make it even more
verbose.  Either way, it's also slow to run.

- Eric

Re: linux-next: build warning after merge of the libcrypto tree

[Eric Biggers]

On Wed, Nov 05, 2025 at 07:55:23PM -0800, Eric Biggers wrote:
> On Thu, Nov 06, 2025 at 02:36:23PM +1100, Stephen Rothwell wrote:
> > Hi all,
> > 
> > After merging the libcrypto tree, today's linux-next build (htmldocs)
> > produced this warning:
> > 
> > WARNING: /home/sfr/kernels/next/next/include/crypto/sha3.h:74 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> >  * Zeroize a sha3_ctx.  This is already called by sha3_final().  Call this
> > 
> > Introduced by commit
> > 
> >   58873ecf091b ("lib/crypto: sha3: Add SHA-3 support")
> 
> Thanks.  Do you know if there's an easy way to find these ahead of time?
> I usually run './scripts/kernel-doc -v -none ${filename}' to catch
> kerneldoc issues.  I did run it on include/crypto/sha3.h, but for some
> reason it doesn't detect this issue.
> 
> 'make htmldocs' doesn't find it either, but does generate a bunch of
> unrelated warnings.  I may be missing an option to make it even more
> verbose.  Either way, it's also slow to run.
> 
> - Eric

Okay, it's because some kernel-doc warnings were accidentally turned off
for everyone :-(  And they just got turned back on by
https://lore.kernel.org/r/20251104215502.1049817-1-andriy.shevchenko@linux.intel.com/
With that applied, './scripts/kernel-doc -v -none include/crypto/sha3.h'
does catch this.

I folded the following into "lib/crypto: sha3: Add SHA-3 support" to
convert the comments starting with "/**" into proper kerneldoc comments:

diff --git a/include/crypto/sha3.h b/include/crypto/sha3.h
index d713b5e3d695..c9e4182ff74f 100644
--- a/include/crypto/sha3.h
+++ b/include/crypto/sha3.h
@@ -66,26 +66,40 @@ struct __sha3_ctx {
 
 void __sha3_update(struct __sha3_ctx *ctx, const u8 *in, size_t in_len);
 
-/** Context for SHA3-224, SHA3-256, SHA3-384, or SHA3-512 */
+/**
+ * struct sha3_ctx - Context for SHA3-224, SHA3-256, SHA3-384, or SHA3-512
+ * @ctx: private
+ */
 struct sha3_ctx {
 	struct __sha3_ctx ctx;
 };
 
 /**
- * Zeroize a sha3_ctx.  This is already called by sha3_final().  Call this
- * explicitly when abandoning a context without calling sha3_final().
+ * sha3_zeroize_ctx() - Zeroize a SHA-3 context
+ * @ctx: The context to zeroize
+ *
+ * This is already called by sha3_final().  Call this explicitly when abandoning
+ * a context without calling sha3_final().
  */
 static inline void sha3_zeroize_ctx(struct sha3_ctx *ctx)
 {
 	memzero_explicit(ctx, sizeof(*ctx));
 }
 
-/** Context for SHAKE128 or SHAKE256 */
+/**
+ * struct shake_ctx - Context for SHAKE128 or SHAKE256
+ * @ctx: private
+ */
 struct shake_ctx {
 	struct __sha3_ctx ctx;
 };
 
-/** Zeroize a shake_ctx.  Call this after the last squeeze. */
+/**
+ * shake_zeroize_ctx() - Zeroize a SHAKE context
+ * @ctx: The context to zeroize
+ *
+ * Call this after the last squeeze.
+ */
 static inline void shake_zeroize_ctx(struct shake_ctx *ctx)
 {
 	memzero_explicit(ctx, sizeof(*ctx));

Re: linux-next: build warning after merge of the libcrypto tree

[Randy Dunlap]

On 11/5/25 7:55 PM, Eric Biggers wrote:
> On Thu, Nov 06, 2025 at 02:36:23PM +1100, Stephen Rothwell wrote:
>> Hi all,
>>
>> After merging the libcrypto tree, today's linux-next build (htmldocs)
>> produced this warning:
>>
>> WARNING: /home/sfr/kernels/next/next/include/crypto/sha3.h:74 This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>  * Zeroize a sha3_ctx.  This is already called by sha3_final().  Call this
>>
>> Introduced by commit
>>
>>   58873ecf091b ("lib/crypto: sha3: Add SHA-3 support")
> 
> Thanks.  Do you know if there's an easy way to find these ahead of time?
> I usually run './scripts/kernel-doc -v -none ${filename}' to catch
> kerneldoc issues.  I did run it on include/crypto/sha3.h, but for some
> reason it doesn't detect this issue.
> 
> 'make htmldocs' doesn't find it either, but does generate a bunch of
> unrelated warnings.  I may be missing an option to make it even more
> verbose.  Either way, it's also slow to run.

Try -Wall, although it may give you more warnings than you care to know about.
You can separately enable these (which are set by -Wall):

There are also:
  -Wreturn, --wreturn   Warns about the lack of a return markup on functions.
  -Wshort-desc, -Wshort-description, --wshort-desc
                        Warns if initial short description is missing

I don't get anything useful from -v unless I am debugging the script.

-- 
~Randy

Re: linux-next: build warning after merge of the libcrypto tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 650 bytes --]

Hi Eric,

On Wed, 5 Nov 2025 20:19:53 -0800 Eric Biggers <ebiggers@kernel.org> wrote:
>
> Okay, it's because some kernel-doc warnings were accidentally turned off
> for everyone :-(  And they just got turned back on by
> https://lore.kernel.org/r/20251104215502.1049817-1-andriy.shevchenko@linux.intel.com/
> With that applied, './scripts/kernel-doc -v -none include/crypto/sha3.h'
> does catch this.

Yeah, I found quite a few warnings today.

> I folded the following into "lib/crypto: sha3: Add SHA-3 support" to
> convert the comments starting with "/**" into proper kerneldoc comments:

Thanks.

-- 
Cheers,
Stephen Rothwell

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]