From 339e005a3a31e47da916b678dbca0a2949ae9ed2 Mon Sep 17 00:00:00 2001
From: David Mitchell <davem@iabyn.com>
Date: Mon, 24 Jun 2024 12:35:01 +0100
Subject: [PATCH] ExtUtils::ParseXS: update pod for error handling

Consolidate the POD for the various warning- and error-raising methods
into a single block of text, to give a better overview of which method
should be used when (e.g. warning vs deferred errors vs die immediately)

The diff looks confusing, but its basically deleting the individual
chunk of pod directly above each method, then adding a complete new
block of pod. This contains completely new text, rather than copying
and pasting.
---
 .../lib/ExtUtils/ParseXS/Utilities.pm         | 115 +++++++-----------
 1 file changed, 46 insertions(+), 69 deletions(-)

diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
index 86d9444e7b950..053565ac5bbee 100644
--- a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
+++ b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS/Utilities.pm
@@ -649,81 +649,78 @@ sub current_line_number {
   return $line_number;
 }
 
-=head2 C<Warn()>
 
-=over 4
 
-=item * Purpose
+=head2 Error handling methods
 
-Print warnings with line number details at the end.
+There are four main methods for reporting warnings and errors.
 
-=item * Arguments
+=over
 
-List of text to output.
+=item C<<$self->Warn(@messages)>>
 
-=item * Return Value
+This is equivalent to:
 
-None.
+  warn "@messages in foo.xs, line 123\n";
 
-=back
+The file and line number are based on the file currently being parsed. It
+is intended for use where you wish to warn, but can continue parsing and
+still generate a correct C output file.
 
-=cut
+=item C<<$self->blurt(@messages)>>
 
-sub Warn {
-  my ($self)=shift;
-  $self->WarnHint(@_,undef);
-}
+This is equivalent to C<Warn>, except that it also increments the internal
+error count (which can be retrieved with C<report_error_count()>). It is
+used to report an error, but where parsing can continue (so typically for
+a semantic error rather than a syntax error). It is expected that the
+caller will eventually signal failure in some fashion. For example,
+C<xsubpp> has this as its last line:
 
-=head2 C<WarnHint()>
+  exit($self->report_error_count() ? 1 : 0);
 
-=over 4
+=item C<<$self->death(@messages)>>
 
-=item * Purpose
+This normally equivalent to:
 
-Prints warning with line number details. The last argument is assumed
-to be a hint string.
+  $self->Warn(@messages);
+  exit(1);
 
-=item * Arguments
+It is used for something like a syntax error, where parsing can't
+continue.  However, this is inconvenient for testing purposes, as the
+error can't be trapped. So if <$self> is created with the C<die_on_error>
+flag, or if C<$ExtUtils::ParseXS::DIE_ON_ERROR> is true when process_file()
+is called, then instead it will die() with that message.
 
-List of strings to warn, followed by one argument representing a hint.
-If that argument is defined then it will be split on newlines and output
-line by line after the main warning.
+=item C<<$self->WarnHint(@messages, $hints)>>
 
-=item * Return Value
+This is a more obscure twin to C<Warn>, which does the same as C<Warn>,
+but afterwards, outputs any lines contained in the <$hints> string, with
+each line wrapped in parentheses. For example:
 
-None.
+  $self->WarnHint(@messages,
+    "Have you set the foo switch?\nSee the manual for further info");
 
 =back
 
 =cut
 
-sub WarnHint {
-  warn _MsgHint(@_);
-}
-
-=head2 C<_MsgHint()>
-
-=over 4
 
-=item * Purpose
+# see L</Error handling methods> above
 
-Constructs an exception message with line number details. The last argument is
-assumed to be a hint string.
-
-=item * Arguments
-
-List of strings to warn, followed by one argument representing a hint.
-If that argument is defined then it will be split on newlines and concatenated
-line by line (parenthesized) after the main message.
+sub Warn {
+  my ($self)=shift;
+  $self->WarnHint(@_,undef);
+}
 
-=item * Return Value
 
-The constructed string.
+# see L</Error handling methods> above
 
-=back
+sub WarnHint {
+  warn _MsgHint(@_);
+}
 
-=cut
 
+# see L</Error handling methods> above
 
 sub _MsgHint {
   my $self = shift;
@@ -736,19 +733,8 @@ sub _MsgHint {
   return $ret;
 }
 
-=head2 C<blurt()>
-
-=over 4
-
-=item * Purpose
-
-=item * Arguments
-
-=item * Return Value
-
-=back
 
-=cut
+# see L</Error handling methods> above
 
 sub blurt {
   my $self = shift;
@@ -756,19 +742,8 @@ sub blurt {
   $self->{errors}++
 }
 
-=head2 C<death()>
-
-=over 4
-
-=item * Purpose
 
-=item * Arguments
-
-=item * Return Value
-
-=back
-
-=cut
+# see L</Error handling methods> above
 
 sub death {
   my ($self) = (@_);
@@ -781,6 +756,7 @@ sub death {
   exit 1;
 }
 
+
 =head2 C<check_conditional_preprocessor_statements()>
 
 =over 4
@@ -889,6 +865,7 @@ sub report_typemap_failure {
   return();
 }
 
+
 1;
 
 # vim: ts=2 sw=2 et: