From 55883c12df9b8af11f39bf2ea6b8cf245ae5ef66 Mon Sep 17 00:00:00 2001
From: Bodo Hugo Barwich <b.barwich@hotmail.com>
Date: Sat, 6 Nov 2021 11:20:09 +0000
Subject: [PATCH] extending documentation on MetaCPAN::Script::Mapping methods

---
 lib/MetaCPAN/Role/Script.pm    |   6 +-
 lib/MetaCPAN/Script/Mapping.pm | 109 +++++++++++++++++++++++++++++++++
 2 files changed, 112 insertions(+), 3 deletions(-)

diff --git a/lib/MetaCPAN/Role/Script.pm b/lib/MetaCPAN/Role/Script.pm
index c5d046d74..9da4edbf8 100644
--- a/lib/MetaCPAN/Role/Script.pm
+++ b/lib/MetaCPAN/Role/Script.pm
@@ -267,7 +267,7 @@ sub check_health {
             my $sinfo_rs
                 = $self->es->cat->indices( h => [ 'index', 'health' ] );
 
-            %{ $self->indices_info } = ();
+            $self->indices_info({});
 
             while ( $sinfo_rs =~ /^([^[:space:]]+) +([^[:space:]]+)/gm ) {
                 $self->indices_info->{$1}
@@ -289,7 +289,7 @@ sub check_health {
             my $sinfo_rs
                 = $self->es->cat->aliases( h => [ 'alias', 'index' ] );
 
-            %{ $self->aliases_info } = ();
+            $self->aliases_info({});
 
             while ( $sinfo_rs =~ /^([^[:space:]]+) +([^[:space:]]+)/gm ) {
                 $self->aliases_info->{$1}
@@ -324,7 +324,7 @@ sub await {
                             . " : ready"
                     };
 
-                    %{ $self->cluster_info } = ( %{ $es->info } );
+                    $self->cluster_info( \%{ $es->info } );
                 }
             };
 
diff --git a/lib/MetaCPAN/Script/Mapping.pm b/lib/MetaCPAN/Script/Mapping.pm
index 4c94a73af..f06663481 100644
--- a/lib/MetaCPAN/Script/Mapping.pm
+++ b/lib/MetaCPAN/Script/Mapping.pm
@@ -595,6 +595,12 @@ __PACKAGE__->meta->make_immutable;
 
 __END__
 
+=pod
+
+=head1 NAME
+
+MetaCPAN::Script::Mapping - Script to set the index and mapping the types
+
 =head1 SYNOPSIS
 
  # bin/metacpan mapping --show_cluster_info   # show basic info about the cluster, indices and aliases
@@ -615,3 +621,106 @@ __END__
 This is the index mapping handling script.
 Used rarely, but carries the most important task of setting
 the index and mapping the types.
+
+=head1 OPTIONS
+
+This Script accepts the following options
+
+=over 4
+
+=item Option C<--show_cluster_info>
+
+This option makes the Script show basic information about the I<ElasticSearch> Cluster
+and its indices and aliases.
+This information has to be collected with the C<MetaCPAN::Role::Script::check_health()> Method.
+On Script start-up it is empty.
+
+    bin/metacpan mapping --show_cluster_info
+
+See L<Method C<MetaCPAN::Role::Script::check_health()>>
+
+=item Option C<--delete>
+
+This option makes the Script delete all indices configured in the project and re-create them emtpy.
+It verifies the index integrity of the indices and aliases calling the methods
+C<MetaCPAN::Role::Script::check_health()> and C<verify_mapping()>.
+If the C<verify_mapping()> Method fails it exits the Script
+with B<Exit Code> C< 1 >.
+
+    bin/metacpan mapping --delete
+
+See L<Method C<deploy_mapping()>>
+
+See L<Method C<verify_mapping()>>
+
+See L<Method C<MetaCPAN::Role::Script::check_health()>>
+
+=item Option C<--all>
+
+This option is only effective in combination with Option C<--delete>.
+It uses the information gathered by C<MetaCPAN::Role::Script::check_health()> to delete
+B<ALL> indices in the I<ElasticSearch> Cluster.
+This option is usefull to reconstruct a broken I<ElasticSearch> Cluster
+
+    bin/metacpan mapping --delete --all
+
+See L<Option C<--delete>>
+
+See L<Method C<deploy_mapping()>>
+
+See L<Method C<MetaCPAN::Role::Script::check_health()>>
+
+=back
+
+=head1 METHODS
+
+This Package provides the following methods
+
+=over 4
+
+=item C<deploy_mapping()>
+
+Deletes and re-creates the indices and aliases defined in the Project.
+The user will be requested for manual confirmation on the command line before the elemination.
+The integrity of the indices and aliases will be checked with the C<verify_mapping()> Method.
+On successful creation it returns C< 1 >, otherwise it returns C< 0 >.
+
+B<Returns:> It returns C< 1 > when the indices and aliases are created and verified as correct.
+Otherwise it returns C< 0 >.
+
+B<Exceptions:> It can throw exceptions when the connection to I<ElasticSearch> fails
+or there is any issue in any I<ElasticSearch> Request run by the Script.
+
+See L<Option C<--delete>>
+
+See L<Method C<verify_mapping()>>
+
+See L<Method C<MetaCPAN::Role::Script::check_health()>>
+
+=item C<verify_mapping( \%indices, \%aliases )>
+
+Checks the defined indices and aliases against the actually in the I<ElasticSearch> Cluster
+existing indices and aliases which must have been requested with
+the C<MetaCPAN::Role::Script::check_health()> Method.
+
+B<Parameters:>
+
+C<\%indices> - Reference to a hash that defines the indices required for the Project.
+
+C<\%aliases> - Reference to a hash that defines the aliases required for the Project.
+
+B<Returns:> It returns C< 1 > when the indices and aliases are created and verified as correct.
+Otherwise it returns C< 0 >.
+
+B<Exceptions:> It can throw exceptions when the connection to I<ElasticSearch> fails
+or there is any issue in any I<ElasticSearch> Request run by the Script.
+
+See L<Option C<--delete>>
+
+See L<Method C<verify_mapping()>>
+
+See L<Method C<MetaCPAN::Role::Script::check_health()>>
+
+=back
+
+=cut