From a9d0eaf34a26d3ddd1007e2ca9d949b15159140f Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
Date: Thu, 13 Jun 2024 16:45:59 -0400
Subject: [PATCH] wikiheaders: Warn if a function returns non-void but has no
 `\returns` line.

---
 build-scripts/wikiheaders.pl | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index 42e8fa61fa..3e728d9442 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -1813,6 +1813,7 @@ if ($copy_direction == 1) {  # --copy-to-headers
         my %params = ();  # have to parse these and build up the wiki tables after, since Markdown needs to know the length of the largest string.  :/
         my @paramsorder = ();
         my $fnsigparams = $headersymsparaminfo{$sym};
+        my $has_returns = 0;
 
         while (@doxygenlines) {
             my $l = shift @doxygenlines;
@@ -1851,6 +1852,7 @@ if ($copy_direction == 1) {  # --copy-to-headers
                 $params{$arg} = $desc;
                 push @paramsorder, $arg;
             } elsif ($l =~ /\A\\r(eturns?)\s+(.*)\Z/) {
+                $has_returns = 1;
                 # !!! FIXME: complain if this isn't a function or macro.
                 my $retstr = "R$1";  # "Return" or "Returns"
                 my $desc = $2;
@@ -1937,6 +1939,10 @@ if ($copy_direction == 1) {  # --copy-to-headers
             }
         }
 
+        if (($symtype == 1) && ($headersymsrettype{$sym} ne 'void') && !$has_returns) {
+            print STDERR "WARNING: Function '$sym' has a non-void return type but no '\\returns' declaration\n";
+        }
+
         # Make sure %params is in the same order as the actual function signature and add C datatypes...
         my $params_has_c_datatype = 0;
         my @final_params = ();