From c0c0c64a1d5cf53a8956118366eb7a32f3a1a56c Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
Date: Fri, 14 Jun 2024 01:57:48 -0400
Subject: [PATCH] wikiheaders: Some quick scripting to make params/return info
 consistent.

- Lowercase the first letter of \param and \returns data; in the former case,
  it looks better in the table and Doxyggen (imho), in the latter it's because
  it's inserted after the word "Returns" to make an english sentence on the
  wiki. This is disabled in this commit, but it was useful to turn it on to
  fix up the headers manually.

- Make sure everything ends with punctuation. Inserts a period if there's
  no existing period or exclamation point at the end of the text. This is
  enabled going forward, so we won't have to manage it ourselves.
---
 build-scripts/wikiheaders.pl | 31 ++++++++++++++++++++++++-------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index 52e357811..6b4dac657 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -1835,6 +1835,18 @@ if ($copy_direction == 1) {  # --copy-to-headers
 
                 $desc =~ s/[\s\n]+\Z//ms;
 
+                if (0) {  # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful.
+                    if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) {
+                        print STDERR "WARNING: $sym\'s '\\param $arg' text starts with a capital letter: '$desc'. Fixing.\n";
+                        $desc = lcfirst($desc);
+                    }
+                }
+
+                if (not $desc =~ /[\.\!]\Z/) {
+                    print STDERR "WARNING: $sym\'s '\\param $arg' text doesn't end with punctuation: '$desc'. Fixing.\n";
+                    $desc .= '.';
+                }
+
                 # Validate this param.
                 if (defined($params{$arg})) {
                     print STDERR "WARNING: Symbol '$sym' has multiple '\\param $arg' declarations! Only keeping the first one!\n";
@@ -1857,13 +1869,6 @@ if ($copy_direction == 1) {  # --copy-to-headers
                 my $retstr = "R$1";  # "Return" or "Returns"
                 my $desc = $2;
 
-                if (0) {  # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful.
-                    if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) {
-                        print STDERR "WARNING: $sym\'s '\\returns' text starts with a capital letter: '$desc'. Fixing.\n";
-                        $desc = lcfirst($desc);
-                    }
-                }
-
                 while (@doxygenlines) {
                     my $subline = $doxygenlines[0];
                     $subline =~ s/\A\s*//;
@@ -1877,6 +1882,18 @@ if ($copy_direction == 1) {  # --copy-to-headers
                 }
                 $desc =~ s/[\s\n]+\Z//ms;
 
+                if (0) {  # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful.
+                    if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) {
+                        print STDERR "WARNING: $sym\'s '\\returns' text starts with a capital letter: '$desc'. Fixing.\n";
+                        $desc = lcfirst($desc);
+                    }
+                }
+
+                if (not $desc =~ /[\.\!]\Z/) {
+                    print STDERR "WARNING: $sym\'s '\\returns' text doesn't end with punctuation: '$desc'. Fixing.\n";
+                    $desc .= '.';
+                }
+
                 # Make sure the \returns info is valid.
                 my $rettype = $headersymsrettype{$sym};
                 die("Don't have a rettype for '$sym' for some reason!") if (($symtype == 1) && (not defined($rettype)));