(#7561) Complete help text for all faces and actions

Faces help output relies on input from the documentation methods in each
of the faces to be documented. This commit calls those methods in each of our
faces, with varying levels of detail depending on their complexity.

1 files changed, 29 insertions, 26 deletions

diff --git a/lib/puppet/indirector/face.rb b/lib/puppet/indirector/face.rb
index 1371c647e..f6c36e31d 100644
--- a/lib/puppet/indirector/face.rb
+++ b/lib/puppet/indirector/face.rb
@@ -2,22 +2,22 @@ require 'puppet/face'
 
 class Puppet::Indirector::Face < Puppet::Face
   option "--terminus TERMINUS" do
-    summary "The indirector terminus to use for this action"
+    summary "The indirector terminus to use for this action."
     description <<-EOT
-Indirector faces expose indirected subsystems of Puppet. These
-subsystems are each able to retrieve and alter a specific type of data
-(with the familiar actions of `find`, `search`, `save`, and `destroy`)
-from an arbitrary number of pluggable backends. In Puppet parlance,
-these backends are called terminuses.
-
-Almost all indirected subsystems have a `rest` terminus that interacts
-with the puppet master's data. Most of them have additional terminuses
-for various local data models, which are in turn used by the indirected
-subsystem on the puppet master whenever it receives a remote request.
-
-The terminus for an action is often determined by context, but
-occasionally needs to be set explicitly. See the "Notes" section of this
-face's manpage for more details.
+      Indirector faces expose indirected subsystems of Puppet. These
+      subsystems are each able to retrieve and alter a specific type of data
+      (with the familiar actions of `find`, `search`, `save`, and `destroy`)
+      from an arbitrary number of pluggable backends. In Puppet parlance,
+      these backends are called terminuses.
+      
+      Almost all indirected subsystems have a `rest` terminus that interacts
+      with the puppet master's data. Most of them have additional terminuses
+      for various local data models, which are in turn used by the indirected
+      subsystem on the puppet master whenever it receives a remote request.
+      
+      The terminus for an action is often determined by context, but
+      occasionally needs to be set explicitly. See the "Notes" section of this
+      face's manpage for more details.
     EOT
 
     before_action do |action, args, options|
@@ -49,36 +49,39 @@ face's manpage for more details.
   end
 
   action :destroy do
-    summary "Delete an object"
+    summary "Delete an object."
+    arguments "<key>"
     when_invoked { |key, options| call_indirection_method(:destroy, key, options) }
   end
 
   action :find do
-    summary "Retrieve an object by name"
+    summary "Retrieve an object by name."
+    arguments "<key>"
     when_invoked { |key, options| call_indirection_method(:find, key, options) }
   end
 
   action :save do
-    summary "Create or modify an object"
-    notes <<-EOT
-      Save actions cannot currently be invoked from the command line, and are
-      for API use only.
+    summary "Create or overwrite an object."
+    arguments "<object>"
+    description <<-EOT
+      Create or overwrite an object. Save actions cannot currently be
+      invoked from the command line, and are for API use only.
     EOT
     when_invoked { |key, options| call_indirection_method(:save, key, options) }
   end
 
   action :search do
-    summary "Search for an object"
+    summary "Search for an object or retrieve multiple objects."
+    arguments "<query>"
     when_invoked { |key, options| call_indirection_method(:search, key, options) }
   end
 
   # Print the configuration for the current terminus class
   action :info do
-    summary "Print the default terminus class for this face"
+    summary "Print the default terminus class for this face."
     description <<-EOT
-      TK So this is per-face, right? No way to tell what the default terminus
-      is per-action, for subsystems that switch to REST for save but query
-      locally for find?
+      Prints the default terminus class for this face. Note that
+      different run modes may have different default terminuses.
     EOT
 
     when_invoked do |*args|