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

diff --git a/lib/puppet/face/catalog/select.rb b/lib/puppet/face/catalog/select.rb
index a6c97a627..d86963e75 100644
--- a/lib/puppet/face/catalog/select.rb
+++ b/lib/puppet/face/catalog/select.rb
@@ -2,21 +2,28 @@
 Puppet::Face.define(:catalog, '0.0.1') do
   action :select do
     summary "Select and show a list of resources of a given type"
-    description <<-EOT
+    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]).
+    EOT
+    description <<-'EOT'
       Retrieves a catalog for the specified host and returns an array of
-      resources of the given type. This action is not intended for
-      command-line use.
+      resources of the given type.
     EOT
-    notes <<-NOTES
-      The type name for this action must be given in its capitalized form.
-      That is, calling `catalog select mynode file` will return an empty
-      array, whereas calling it with 'File' will return a list of the node's
-      file resources.
-
+    notes <<-'NOTES'
       By default, this action will retrieve a catalog from Puppet's compiler
       subsystem; you must call the action with `--terminus rest` if you wish
       to retrieve a catalog from the puppet master.
+
+      FORMATTING ISSUES: This action cannot currently render useful yaml;
+      instead, it returns an entire catalog. Use json instead.
     NOTES
+    examples <<-'EOT'
+      Ask the puppet master for a list of managed file resources for a node:
+
+      $ puppet catalog select --terminus rest somenode.magpie.lan file
+    EOT
     when_invoked do |host, type, options|
       # REVISIT: Eventually, type should have a default value that triggers
       # the non-specific behaviour.  For now, though, this will do.