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|