From e43d075ace85f0657e1d1fc3ac68f8e826227276 Mon Sep 17 00:00:00 2001
From: Jacob Bachmeyer <jcb@gnu.org>
Date: Sat, 3 Jun 2023 22:32:44 -0500
Subject: [PATCH] Add documentation for exception accessor methods

---
 gatekeeper.pl | 94 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 83 insertions(+), 11 deletions(-)

diff --git a/gatekeeper.pl b/gatekeeper.pl
index 16a1863..ae3159d 100755
--- a/gatekeeper.pl
+++ b/gatekeeper.pl
@@ -885,23 +885,14 @@ BEGIN {
 
 =head2 Exception Definitions and Utilities
 
-=over
-
 =cut
 
 {
   package Local::Exception;
 
-  sub type	{ (shift)->{type}	}
-  sub summary	{ (shift)->{summary}	}
-
-  sub type_p {
-    my $self = shift;
-    my $query = shift;
-
-    return $self->{type} eq $query
-  }
+=head3 Throwing Exceptions
 
+=over
 
 =item throw $type => ($key => $value)...
 
@@ -928,10 +919,91 @@ called as a function.
       die $ob;
     }
 
+=back
+
+=head3 General Accessors
+
+All exceptions have these instance methods:
+
+=over
+
+=item $type = $@->type
+
+Return the type of an exception, as its abbreviated name as a string.
+
+=cut
+
+  sub type	{ (shift)->{type}	}
+
+=item $summary_message = $@->summary
+
+Return a summary message for an exception, suitable for the log.
+
+=cut
+
+  sub summary	{ (shift)->{summary}	}
+
+=item $boolean = $@->type_p($type)
+
+Test if an exception is of a specific type.
+
+=cut
+
+  sub type_p {
+    my $self = shift;
+    my $query = shift;
+
+    return $self->{type} eq $query
+  }
 }
 
 BEGIN { *throw = \&Local::Exception::throw }
 
+=back
+
+=head3 Optional Exception Accessors
+
+Some exception types have these access methods:
+
+=over
+
+=item $message = $@->message
+
+Return a detailed message describing the exception, suitable for
+presentation to a user.
+
+=item $package_name = $@->package_name
+
+For errors caused by an unknown or misconfigured package, return the name
+of the package requested but not available.
+
+=item $directory = $@->directory
+
+For syntax errors, return the directory requested, if known.  A missing
+directory key in a directive results in a directive syntax exception where
+this is an undefined value.
+
+=item $trace = $@->trace
+
+For syntax errors, return the internal parse trace object, which is an
+arrayref for an array of arrays.
+
+=item $message = $@->trace_msg
+
+For syntax errors, return a textual description of the parse trace.
+
+=item $sig_info = $@->sig_info
+
+For signature errors, return the signature information object representing
+the report from gpgv.
+
+=item $command = $@->command
+
+For processing errors, return the internal descriptor for the operation
+that encountered the error, which is an arrayref.
+
+=cut
+
 {
   package Local::Exception::package_configuration;
   {our @ISA = qw(Local::Exception)}
-- 
2.25.1