SDL: wikiheaders.pl: Report a function's header file name.

From 02246aaeb95531d1fab55baabfc43acfb153884f Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Sun, 31 Mar 2024 12:56:00 -0400
Subject: [PATCH] wikiheaders.pl: Report a function's header file name.

(cherry picked from commit e055a9fc2d98351bbfb9de553ee215a318da780f)
---
 .wikiheaders-options         |  2 ++
 build-scripts/wikiheaders.pl | 31 +++++++++++++++++++++++++------
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/.wikiheaders-options b/.wikiheaders-options
index 634840e89f58b..d8e091fb8fa71 100644
--- a/.wikiheaders-options
+++ b/.wikiheaders-options
@@ -15,3 +15,5 @@ wikiurl = https://wiki.libsdl.org/SDL2
 bugreporturl = https://github.com/libsdl-org/sdlwiki/issues/new
 warn_about_missing = 0
 wikipreamble = (This is the legacy documentation for stable SDL2, the current stable version; [SDL3](https://wiki.libsdl.org/SDL3/) is the current development version.)
+wikiheaderfiletext = Defined in [%fname%](https://github.com/libsdl-org/SDL/blob/SDL2/include/%fname%), but apps should _only_ `#include "SDL.h"`!
+manpageheaderfiletext = Defined in %fname%, but apps should only #include "SDL.h"!
diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index bf26d64332a2f..4bdfd5afa1552 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -28,6 +28,8 @@
 my $copy_direction = 0;
 my $optionsfname = undef;
 my $wikipreamble = undef;
+my $wikiheaderfiletext = 'Defined in %fname%';
+my $manpageheaderfiletext = 'Defined in %fname%';
 my $changeformat = undef;
 
 foreach (@ARGV) {
@@ -84,6 +86,8 @@
             $wikiurl = $val, next if $key eq 'wikiurl';
             $bugreporturl = $val, next if $key eq 'bugreporturl';
             $wikipreamble = $val, next if $key eq 'wikipreamble';
+            $wikiheaderfiletext = $val, next if $key eq 'wikiheaderfiletext';
+            $manpageheaderfiletext = $val, next if $key eq 'manpageheaderfiletext';
         }
     }
     close(OPTIONS);
@@ -485,6 +489,7 @@ sub usage {
     'Draft',
     '[Brief]',
     'Deprecated',
+    'Header File',
     'Syntax',
     'Function Parameters',
     'Return Value',
@@ -499,7 +504,8 @@ sub usage {
 #  not found in the headers.
 my %only_wiki_sections = (  # The ones don't mean anything, I just need to check for key existence.
     'Draft', 1,
-    'Code Examples', 1
+    'Code Examples', 1,
+    'Header File', 1
 );
 
 
@@ -1220,6 +1226,10 @@ sub usage {
             }
         }
 
+        my $hfiletext = $wikiheaderfiletext;
+        $hfiletext =~ s/\%fname\%/$headerfuncslocation{$fn}/g;
+        $sections{'Header File'} = "$hfiletext\n";
+
         # Make sure this ends with a double-newline.
         $sections{'Related Functions'} .= "\n" if defined $sections{'Related Functions'};
 
@@ -1464,6 +1474,10 @@ sub usage {
         my $related = $sectionsref->{'Related Functions'};
         my $examples = $sectionsref->{'Code Examples'};
         my $deprecated = $sectionsref->{'Deprecated'};
+        my $headerfile = $manpageheaderfiletext;
+        $headerfile =~ s/\%fname\%/$headerfuncslocation{$fn}/g;
+        $headerfile .= "\n";
+
         my $brief = $sectionsref->{'[Brief]'};
         my $decl = $headerdecls{$fn};
         my $str = '';
@@ -1509,6 +1523,16 @@ sub usage {
         $str .= " \\- $brief" if (defined $brief);
         $str .= "\n";
 
+        if (defined $deprecated) {
+            $str .= ".SH DEPRECATED\n";
+            $str .= dewikify($wikitype, $deprecated) . "\n";
+        }
+
+        if (defined $headerfile) {
+            $str .= ".SH HEADER FILE\n";
+            $str .= dewikify($wikitype, $headerfile) . "\n";
+        }
+
         $str .= ".SH SYNOPSIS\n";
         $str .= ".nf\n";
         $str .= ".B #include \\(dq$mainincludefname\\(dq\n";
@@ -1525,11 +1549,6 @@ sub usage {
             $str .= $remarks . "\n";
         }
 
-        if (defined $deprecated) {
-            $str .= ".SH DEPRECATED\n";
-            $str .= dewikify($wikitype, $deprecated) . "\n";
-        }
-
         if (defined $params) {
             $str .= ".SH FUNCTION PARAMETERS\n";
             my @lines = split /\n/, $params;