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