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

(cherry picked from commit e055a9fc2d)

.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"!

build-scripts/wikiheaders.pl

@@ -28,6 +28,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;
 
 foreach (@ARGV) {
@@ -84,6 +86,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);
@@ -485,6 +489,7 @@ my @standard_wiki_sections = (
     'Draft',
     '[Brief]',
     'Deprecated',
+    'Header File',
     'Syntax',
     'Function Parameters',
     'Return Value',
@@ -499,7 +504,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
 );
 
 
@@ -1220,6 +1226,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'};
 
@@ -1464,6 +1474,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 = '';
@@ -1509,6 +1523,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";
@@ -1525,11 +1549,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;