(#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, 5 insertions, 5 deletions

diff --git a/lib/puppet/face/catalog/select.rb b/lib/puppet/face/catalog/select.rb
index d86963e75..de2ca803b 100644
--- a/lib/puppet/face/catalog/select.rb
+++ b/lib/puppet/face/catalog/select.rb
@@ -1,15 +1,15 @@
 # Select and show a list of resources of a given type.
 Puppet::Face.define(:catalog, '0.0.1') do
   action :select do
-    summary "Select and show a list of resources of a given type"
+    summary "Retrieve a catalog and filter it for resources of a given type."
     arguments "<host> <resource_type>"
     returns <<-'EOT'
-      An array of resource objects excised from a catalog. When used at
-      the command line, returns a list of resource references (Type[title]).
+      A list of resource references ("Type[title]"). When used from the API,
+      returns an array of Puppet::Resource objects excised from a catalog.
     EOT
     description <<-'EOT'
-      Retrieves a catalog for the specified host and returns an array of
-      resources of the given type.
+      Retrieves a catalog for the specified host, then searches it for all
+      resources of the requested type.
     EOT
     notes <<-'NOTES'
       By default, this action will retrieve a catalog from Puppet's compiler