(#7764, 7775, 7778) Revisions to Faces help text

Per UX review of help text, this commit makes several changes over the breadth
of the Faces help:

* Preface API-only action summaries/descriptions with "API only." (issue #7775)
* Provide both CLI and API info in "returns," with the CLI info first. (issue #7778)
* Summaries should be sentences. (Add punctuation.)
* First sentences of descriptions should reiterate summaries. (Summaries and
  descriptions should be displayed far enough apart that this isn't a problem.)
* Standardize on "subcommand" instead of "face" when talking about the entity
  you invoke at the command line. (Use "face" when describing API use.)
* Fix outdated or clunky text in several faces.

1 files changed, 7 insertions, 5 deletions

diff --git a/lib/puppet/indirector/face.rb b/lib/puppet/indirector/face.rb
index bb8ce2ceb..ead3f4b46 100644
--- a/lib/puppet/indirector/face.rb
+++ b/lib/puppet/indirector/face.rb
@@ -61,11 +61,12 @@ class Puppet::Indirector::Face < Puppet::Face
   end
 
   action :save do
-    summary "Create or overwrite an object."
+    summary "API only: 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.
+      API only: create or overwrite an object. As the Faces framework does not
+      currently accept data from STDIN, save actions cannot currently be invoked
+      from the command line.
     EOT
     when_invoked { |key, options| call_indirection_method(:save, key, options) }
   end
@@ -80,8 +81,9 @@ class Puppet::Indirector::Face < Puppet::Face
   action :info do
     summary "Print the default terminus class for this face."
     description <<-EOT
-      Prints the default terminus class for this face. Note that
-      different run modes may have different default terminuses.
+      Prints the default terminus class for this subcommand. Note that different
+      run modes may have different default termini; when in doubt, specify the
+      run mode with the '--mode' option.
     EOT
 
     when_invoked do |*args|