From 87535d2c867e52f42da40ad9aab2c7ae419746d0 Mon Sep 17 00:00:00 2001
From: Jacob Bachmeyer <jcb@gnu.org>
Date: Fri, 15 Sep 2023 19:19:46 -0500
Subject: [PATCH] Document internal Local::Packet::Directive::Upload class

---
 gatekeeper.pl | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/gatekeeper.pl b/gatekeeper.pl
index 1090f1d..42d3f8c 100755
--- a/gatekeeper.pl
+++ b/gatekeeper.pl
@@ -2328,6 +2328,13 @@ mostly used for constructing messages.
   }
 }
 
+=head3 Local::Packet::Directive::Upload
+
+C<Local::Packet::Directive::Upload> is the (derived) class for packets
+carrying uploaded files.
+
+=cut
+
 {
   package Local::Packet::Directive::Upload;
   {our @ISA = qw(Local::Packet::Directive)}
@@ -2336,13 +2343,38 @@ mostly used for constructing messages.
 
   sub has_uploaded_file { return 1 }
 
+=pod
+
+Additional accessors valid only after the packet has been parsed:
+
+=over
+
+=item $upload_filename = $packet->upload_filename
+
+Return the name of the file uploaded as part of PACKET.  This is the name
+associated with the directive and is the name used in the inbox and scratch
+directories.
+
+=cut
+
   sub upload_filename	{ (shift)->{oplist}->[0][1]->{filename}  }
 
+=item ($filename, $sig_filename) = $packet->target_filepair
+
+Return the names of the uploaded file and its detached signature in that
+order.  This is used to construct a message reporting success.
+
+=cut
+
   sub target_filepair {
     my $filename = (shift)->upload_filename;
     return $filename, $filename.'.sig';
   }
 
+=back
+
+=cut
+
   sub auth_check {
     my $self = shift;
 
-- 
2.25.1