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

diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index be38ad388..c68d71846 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -3,16 +3,16 @@ Puppet::Indirector::Face.define(:node, '0.0.1') do
   copyright "Puppet Labs", 2011
   license   "Apache 2 license; see COPYING"
 
-  summary "View and manage node definitions"
-
-  description <<-EOT
-    This face interacts with node objects, which are what Puppet uses to
+  summary "View and manage node definitions."
+  description <<-'EOT'
+    This face interacts with node objects, which are used by Puppet to
     build a catalog. A node object consists of the node's facts,
-    environment, additional top-scope variables, and classes.
+    environment, node parameters (exposed in the parser as top-scope
+    variables), and classes.
   EOT
-  notes <<-EOT
-    This is an indirector face, which exposes find, search, save, and
-    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+  notes <<-'EOT'
+    This is an indirector face, which exposes `find`, `search`, `save`, and
+    `destroy` actions for an indirected subsystem of Puppet. Valid termini
     for this face include:
 
     * `active_record`
@@ -23,4 +23,28 @@ Puppet::Indirector::Face.define(:node, '0.0.1') do
     * `rest`
     * `yaml`
   EOT
+
+  get_action(:destroy).summary "Invalid for this face."
+  get_action(:search).summary "Invalid for this face."
+  get_action(:save).summary "Invalid for this face."
+
+  find = get_action(:find)
+  find.summary "Retrieve a node object."
+  find.arguments "<host>"
+  find.returns <<-'EOT'
+    A Puppet::Node object.
+
+    RENDERING ISSUES: Rendering as string and json are currently broken;
+    node objects can only be rendered as yaml.
+  EOT
+  find.examples <<-'EOT'
+    Retrieve an "empty" (no classes, fact and bulit-in parameters only,
+    and an environment of "production") node:
+
+    $ puppet node find somenode.puppetlabs.lan --terminus plain --render-as yaml
+
+    Retrieve a node using the puppet master's configured ENC:
+
+    $ puppet node find somenode.puppetlabs.lan --terminus exec --mode master --render-as yaml
+  EOT
 end