Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Randy Dunlap <rdunlap@infradead.org>
To:     linux-kernel@vger.kernel.org
Cc:     Randy Dunlap <rdunlap@infradead.org>,
        Mimi Zohar <zohar@linux.ibm.com>,
        David Howells <dhowells@redhat.com>,
        David Woodhouse <dwmw2@infradead.org>, keyrings@vger.kernel.org
Subject: [PATCH] certs: system_keyring.c: clean up kernel-doc
Date:   Sun, 24 Oct 2021 17:38:13 -0700
Message-Id: <20211025003813.5164-1-rdunlap@infradead.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

Fix some kernel-doc warnings in system_keyring.c:

system_keyring.c:43: warning: expecting prototype for restrict_link_to_builtin_trusted(). Prototype was for restrict_link_by_builtin_trusted() instead
system_keyring.c:77: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Allocate a struct key_restriction for the "builtin and secondary trust"
system_keyring.c:77: warning: missing initial short description on line:
 * Allocate a struct key_restriction for the "builtin and secondary trust"

Fix the warnings above and then see & fix these:

system_keyring.c:43: warning: No description found for return value of 'restrict_link_by_builtin_trusted'
system_keyring.c:62: warning: No description found for return value of 'restrict_link_by_builtin_and_secondary_trusted'
system_keyring.c:190: warning: No description found for return value of 'verify_pkcs7_message_sig'
system_keyring.c:275: warning: No description found for return value of 'verify_pkcs7_signature'

This still leaves non-exported two functions that do not have their
functions parameters documented: restrict_link_by_builtin_trusted() and
restrict_link_by_builtin_and_secondary_trusted().

Use '%' preceding constants in kernel-doc notation.

Use "builtin" consistently instead of "built in" or "built-in".

Don't use "/**" to begin a comment that is not in kernel-doc format.

Document the use of VERIFY_USE_SECONDARY_KEYRING and
VERIFY_USE_PLATFORM_KEYRING.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Mimi Zohar <zohar@linux.ibm.com>
Cc: David Howells <dhowells@redhat.com>
Cc: David Woodhouse <dwmw2@infradead.org>
Cc: keyrings@vger.kernel.org
---
 certs/system_keyring.c |   30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

--- linux-next-20211022.orig/certs/system_keyring.c
+++ linux-next-20211022/certs/system_keyring.c
@@ -31,10 +31,12 @@ extern __initconst const unsigned long s
 extern __initconst const unsigned long module_cert_size;
 
 /**
- * restrict_link_to_builtin_trusted - Restrict keyring addition by built in CA
+ * restrict_link_by_builtin_trusted - Restrict keyring addition by builtin CA
  *
  * Restrict the addition of keys into a keyring based on the key-to-be-added
- * being vouched for by a key in the built in system keyring.
+ * being vouched for by a key in the builtin system keyring.
+ *
+ * Return: %0 on success or a negative value on error
  */
 int restrict_link_by_builtin_trusted(struct key *dest_keyring,
 				     const struct key_type *type,
@@ -51,8 +53,10 @@ int restrict_link_by_builtin_trusted(str
  *   addition by both builtin and secondary keyrings
  *
  * Restrict the addition of keys into a keyring based on the key-to-be-added
- * being vouched for by a key in either the built-in or the secondary system
+ * being vouched for by a key in either the builtin or the secondary system
  * keyrings.
+ *
+ * Return: %0 on success or a negative value on error
  */
 int restrict_link_by_builtin_and_secondary_trusted(
 	struct key *dest_keyring,
@@ -73,7 +77,7 @@ int restrict_link_by_builtin_and_seconda
 					  secondary_trusted_keys);
 }
 
-/**
+/*
  * Allocate a struct key_restriction for the "builtin and secondary trust"
  * keyring. Only for use in system_trusted_keyring_init().
  */
@@ -170,14 +174,17 @@ late_initcall(load_system_certificate_li
 
 /**
  * verify_pkcs7_message_sig - Verify a PKCS#7-based signature on system data.
- * @data: The data to be verified (NULL if expecting internal data).
+ * @data: The data to be verified (%NULL if expecting internal data).
  * @len: Size of @data.
  * @pkcs7: The PKCS#7 message that is the signature.
- * @trusted_keys: Trusted keys to use (NULL for builtin trusted keys only,
- *					(void *)1UL for all trusted keys).
+ * @trusted_keys: Trusted keys to use (%NULL for builtin trusted keys only,
+ *		  %VERIFY_USE_SECONDARY_KEYRING for secondary trusted keys,
+ *		  %VERIFY_USE_PLATFORM_KEYRING for platform trusted keys).
  * @usage: The use to which the key is being put.
  * @view_content: Callback to gain access to content.
  * @ctx: Context for callback.
+ *
+ * Return: %0 on success or a negative value on error
  */
 int verify_pkcs7_message_sig(const void *data, size_t len,
 			     struct pkcs7_message *pkcs7,
@@ -254,15 +261,18 @@ error:
 
 /**
  * verify_pkcs7_signature - Verify a PKCS#7-based signature on system data.
- * @data: The data to be verified (NULL if expecting internal data).
+ * @data: The data to be verified (%NULL if expecting internal data).
  * @len: Size of @data.
  * @raw_pkcs7: The PKCS#7 message that is the signature.
  * @pkcs7_len: The size of @raw_pkcs7.
- * @trusted_keys: Trusted keys to use (NULL for builtin trusted keys only,
- *					(void *)1UL for all trusted keys).
+ * @trusted_keys: Trusted keys to use (%NULL for builtin trusted keys only,
+ *		  %VERIFY_USE_SECONDARY_KEYRING for secondary trusted keys,
+ *		  %VERIFY_USE_PLATFORM_KEYRING for platform trusted keys).
  * @usage: The use to which the key is being put.
  * @view_content: Callback to gain access to content.
  * @ctx: Context for callback.
+ *
+ * Return: %0 on success or a negative value on error
  */
 int verify_pkcs7_signature(const void *data, size_t len,
 			   const void *raw_pkcs7, size_t pkcs7_len,