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

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

diff --git a/.wikiheaders-options b/.wikiheaders-options
index e11b0a7a0..d8df030fe 100644
--- a/.wikiheaders-options
+++ b/.wikiheaders-options
@@ -15,3 +15,5 @@ wikiurl = https://wiki.libsdl.org
 bugreporturl = https://github.com/libsdl-org/sdlwiki/issues/new
 warn_about_missing = 0
 wikipreamble = (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+wikiheaderfiletext = Defined in [%fname%](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/%fname%), but apps should _only_ `#include <SDL3/SDL.h>`!
+manpageheaderfiletext = Defined in %fname%, but apps should only #include <SDL3/SDL.h>!
diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index 58abdf4ea..598216a87 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -29,6 +29,8 @@ my $warn_about_missing = 0;
 my $copy_direction = 0;
 my $optionsfname = undef;
 my $wikipreamble = undef;
+my $wikiheaderfiletext = 'Defined in %fname%';
+my $manpageheaderfiletext = 'Defined in %fname%';
 my $changeformat = undef;
 my $manpath = undef;
 my $gitrev = undef;
@@ -93,6 +95,8 @@ if (defined $optionsfname) {
             $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);
@@ -498,6 +502,7 @@ my @standard_wiki_sections = (
     'Draft',
     '[Brief]',
     'Deprecated',
+    'Header File',
     'Syntax',
     'Function Parameters',
     'Return Value',
@@ -512,7 +517,8 @@ my @standard_wiki_sections = (
 #  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
 );
 
 
@@ -1272,6 +1278,10 @@ if ($copy_direction == 1) {  # --copy-to-headers
             }
         }
 
+        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'};
 
@@ -1516,6 +1526,10 @@ if ($copy_direction == 1) {  # --copy-to-headers
         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 = '';
@@ -1561,6 +1575,16 @@ if ($copy_direction == 1) {  # --copy-to-headers
         $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";
@@ -1577,11 +1601,6 @@ if ($copy_direction == 1) {  # --copy-to-headers
             $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;