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

diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb
index 969d42389..541468d39 100644
--- a/lib/puppet/face/plugin.rb
+++ b/lib/puppet/face/plugin.rb
@@ -3,29 +3,36 @@ Puppet::Face.define(:plugin, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "Interact with the Puppet plugin system"
-  description <<-EOT
+  summary "Interact with the Puppet plugin system."
+  description <<-'EOT'
     This face provides network access to the puppet master's store of
-    plugins. It is intended for use in other faces, rather than for direct
-    command line access.
+    plugins.
   EOT
-  notes <<-EOT
+  notes <<-'EOT'
     The puppet master can serve 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.
   EOT
 
   action :download do
-    summary "Download plugins from the configured master"
-    returns <<-EOT
-      An array containing the files actually downloaded. If all files
-      were in sync, this array will be empty.
+    summary "Download plugins from the puppet master."
+    description <<-'EOT'
+      Downloads plugins from the configured puppet master. Any plugins
+      downloaded in this way will be used in all subsequent Puppet activity.
     EOT
-    notes "This action modifies files on disk without returning any data."
-    examples <<-EOT
+    returns <<-'EOT'
+      A display-formatted list of the files downloaded. If all plugin
+      files were in sync, this list will be empty.
+    EOT
+    notes "This action modifies files on disk."
+    examples <<-'EOT'
       Retrieve plugins from the puppet master:
 
-          Puppet::Face[:plugin, '0.0.1'].download
+      $ puppet plugin download
+
+      Retrieve plugins from the puppet master (API example):
+
+      $ Puppet::Face[:plugin, '0.0.1'].download
     EOT
 
     when_invoked do |options|