Commit df7ab1b451 for openssl.org
commit df7ab1b45148291a0fd279ef4d6b609534d3ea27
Author: Richard Levitte <levitte@openssl.foundation>
Date: Thu Nov 19 16:25:29 2026 +0100
util/check-doc-comments.pl: accept @retval as a return annotation
Doxygen's @retval documents the individual return values of a
function and is a valid alternative to @return/@returns for a
non-void function. Accept it in the internal-header check so
documentation using @retval pairs does not fail check-style.
Motivated by https://github.com/openssl/openssl/pull/33358, whose
internal DER reader header documents return values with @retval.
Fixes: 9a31116fe657 ("Make a doc comments checker to enforce DOCUMENTATION.md")
Assisted-by: Pi:moonshotai/kimi-k3
Signed-off-by: Richard Levitte <levitte@openssl.foundation>
Reviewed-by: Matt Caswell <matt@openssl.foundation>
Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
Merge-date: Fri Nov 20 17:07:46 2026
Merged-from: https://github.com/openssl/openssl/pull/33849
diff --git a/util/check-doc-comments.pl b/util/check-doc-comments.pl
index e27e22e209..d4d54bd35f 100755
--- a/util/check-doc-comments.pl
+++ b/util/check-doc-comments.pl
@@ -26,10 +26,10 @@
# preceded by a /** ... */ doxygen block containing "@see NAME(3)" for the
# function's own name, and that manual page must exist in the doc/ tree.
# * other (internal) headers: the prototype must be immediately preceded by a
-# /** ... */ block with a @param for each named parameter and a @returns
-# when the return type is not void. When the parameter list cannot be
-# parsed with confidence the @param check is skipped; the block is still
-# required.
+# /** ... */ block with a @param for each named parameter and a @return /
+# @returns / @retval when the return type is not void. When the parameter
+# list cannot be parsed with confidence the @param check is skipped; the
+# block is still required.
#
# Not checked: static functions, non-function declarations (macros, typedefs,
# function-pointer typedefs), and declarations carrying a "doc-exempt" marker.
@@ -171,8 +171,8 @@ sub check_file {
# Report a function's missing tags on one line; they are all fixed
# in the single doxygen block attached to the declaration.
my @clauses;
- push @clauses, "\@returns for the return value"
- if !$p->{ret_void} && $block !~ /\@returns?\b/;
+ push @clauses, "\@return/\@returns/\@retval for the return value"
+ if !$p->{ret_void} && $block !~ /\@(?:returns?|retval)\b/;
my @params;
unless ($p->{params_uncertain}) { # fail open on parse doubt
# Harvest the names doxygen actually documents. Accept an