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

diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb
index 541468d39..76c79f38d 100644
--- a/lib/puppet/face/plugin.rb
+++ b/lib/puppet/face/plugin.rb
@@ -5,13 +5,13 @@ Puppet::Face.define(:plugin, '0.0.1') do
 
   summary "Interact with the Puppet plugin system."
   description <<-'EOT'
-    This face provides network access to the puppet master's store of
+    This subcommand provides network access to the puppet master's store of
     plugins.
-  EOT
-  notes <<-'EOT'
-    The puppet master can serve Ruby code collected from the lib directories
+
+    The puppet master serves Ruby code collected from the `lib` directories
     of its modules. These plugins can be used on agent nodes to extend
-    Facter and implement custom types and providers.
+    Facter and implement custom types and providers. Plugins are normally
+    downloaded by puppet agent during the course of a run.
   EOT
 
   action :download do
@@ -19,12 +19,13 @@ Puppet::Face.define(:plugin, '0.0.1') do
     description <<-'EOT'
       Downloads plugins from the configured puppet master. Any plugins
       downloaded in this way will be used in all subsequent Puppet activity.
+      This action modifies files on disk.
     EOT
     returns <<-'EOT'
-      A display-formatted list of the files downloaded. If all plugin
-      files were in sync, this list will be empty.
+      A list of the files downloaded, or a confirmation that no files were
+      downloaded. When used from the Ruby API, this action returns an array of
+      the files downloaded, which will be empty if none were retrieved.
     EOT
-    notes "This action modifies files on disk."
     examples <<-'EOT'
       Retrieve plugins from the puppet master: