From 06b85ada00cbe006cb7bd6b4b1effca0a892625e Mon Sep 17 00:00:00 2001
From: Jacob Bachmeyer <jcb@gnu.org>
Date: Sat, 5 Aug 2023 22:07:07 -0500
Subject: [PATCH] Add documentation for operation list classes

---
 gatekeeper.pl | 49 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/gatekeeper.pl b/gatekeeper.pl
index c091ed0..94d91ef 100755
--- a/gatekeeper.pl
+++ b/gatekeeper.pl
@@ -1593,15 +1593,23 @@ sub read_directive_from_string {
 
 =head2 Operation list helper classes
 
-=over
+The operation list abstraction provides a concise way to express the steps
+needed to process an upload, independent of the type of the upload.
 
-=item TODO
+=over
 
 =cut
 
 {
   package Local::OpList;
 
+=item $oplist = Local::OpList->new(@ops)
+
+Construct an operation list object containing OPS.  The elements of OPS are
+arrayrefs as described below.
+
+=cut
+
   sub new {
     my $class = shift;
     my @ops = @_;
@@ -1620,6 +1628,14 @@ sub read_directive_from_string {
     bless \@ops, $class
   }
 
+=item $oplist->check
+
+Validate the operations in OPLIST.  This allows to detect some types of
+problems before any operations are performed, to reduce the scenarios where
+an upload packet can be partially processed.
+
+=cut
+
   sub check {
     my $self = shift;
     my $info = $self->[0][1];	# obtain hash from header
@@ -1627,6 +1643,12 @@ sub read_directive_from_string {
     foreach my $step (@$self) { $step->check($info) }
   }
 
+=item $oplist->execute
+
+Perform the operations in OPLIST.
+
+=cut
+
   sub execute {
     my $self = shift;
     my $info = $self->[0][1];	# obtain hash from header
@@ -1635,9 +1657,25 @@ sub read_directive_from_string {
   }
 }
 
+=back
+
+Each element of an operation list is itself an arrayref as follows:
+
+=over
+
+=cut
+
 {
   package Local::OpList::Op_header;
 
+=item [ header =E<gt> { packet =E<gt> $packet, ... } ]
+
+This is always the first item in an operation list and contains a weak
+reference to the parent packet object at the C<packet> key in a hash.  The
+entire hash is passed to all other operation list handlers.
+
+=cut
+
   sub check {}
   sub execute {}
 }
@@ -1797,6 +1835,13 @@ Remove the symlink at LINKNAME.
 {
   package Local::OpList::Op_archive;
 
+=item [ archive =E<gt> $filename ]
+
+Move FILENAME (and its detached signature) from the managed public file
+tree to the archive file tree.
+
+=cut
+
   sub check {}
 
   sub execute {
-- 
2.25.1