(#6962) Fill out documentation on Faces and Actions

This uses the documentation we had written, wiring it into the existing faces
and actions.  This helps fill out the need to document these things before
they ship.

5 files changed, 24 insertions, 11 deletions

diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 59356d43f..da03af0fd 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -3,14 +3,18 @@ require 'puppet/face/indirector'
 Puppet::Face::Indirector.define(:catalog, '0.0.1') do
   summary "Compile, save, view, and convert catalogs."
 
-  @longdocs = "This face primarily interacts with the compiling subsystem.
-  By default, it compiles a catalog using the default manifest and the
-  hostname from 'certname', but you can choose to retrieve a catalog from
-  the server by specifying '--from rest'.  You can also choose to print any
-  catalog in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
-  with '--format dot'."
+  description <<-EOT
+This face primarily interacts with the compiling subsystem.
+By default, it compiles a catalog using the default manifest and the
+hostname from 'certname', but you can choose to retrieve a catalog from
+the server by specifying '--from rest'.  You can also choose to print any
+catalog in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
+with '--format dot'.
+  EOT
 
   action(:apply) do
+    summary "apply a Puppet::Resource::Catalog object"
+
     when_invoked do |catalog, options|
       report = Puppet::Transaction::Report.new("apply")
       report.configuration_version = catalog.version
@@ -32,6 +36,8 @@ Puppet::Face::Indirector.define(:catalog, '0.0.1') do
   end
 
   action(:download) do
+    summary "download the catalog given the certname and facts"
+
     when_invoked do |certname, facts, options|
       Puppet::Resource::Catalog.indirection.terminus_class = :rest
       facts_to_upload = {:facts_format => :b64_zlib_yaml, :facts => CGI.escape(facts.render(:b64_zlib_yaml))}
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index a5a279ddf..abcb3369a 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -4,8 +4,9 @@ require 'puppet/node/facts'
 Puppet::Face::Indirector.define(:facts, '0.0.1') do
   summary "Retrieve, store, and view facts."
 
-  # Upload our facts to the server
   action(:upload) do
+    summary "upload our facts to the server."
+
     render_as :yaml
 
     when_invoked do |options|
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index c85345167..0988ebea2 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -3,6 +3,9 @@ require 'puppet/face/indirector'
 Puppet::Face::Indirector.define(:key, '0.0.1') do
   summary "Create, save, and remove certificate keys."
 
-  @longdocs = "Keys are created for you automatically when certificate
-  requests are generated with 'puppet certificate generate'."
+  description <<-EOT
+Keys are created for you automatically when certificate
+requests are generated with 'puppet certificate generate'.
+  EOT
+
 end
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index 7032debc3..7cb6ae469 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -2,6 +2,7 @@ require 'puppet/face/indirector'
 Puppet::Face::Indirector.define(:node, '0.0.1') do
   summary "View and manage nodes"
 
-  @longdocs = "It defaults to using whatever your node
-  terminus is set as."
+  description <<-EOT
+It defaults to using whatever your node terminus is set as.
+  EOT
 end
diff --git a/lib/puppet/face/secret_agent.rb b/lib/puppet/face/secret_agent.rb
index af7ffb7b7..90841b9e0 100644
--- a/lib/puppet/face/secret_agent.rb
+++ b/lib/puppet/face/secret_agent.rb
@@ -4,6 +4,8 @@ Puppet::Face.define(:secret_agent, '0.0.1') do
   summary "Provides agent-like behavior, with no plugin downloading or reporting."
 
   action(:synchronize) do
+    summary "run the secret agent, which makes the catalog and system match..."
+
     when_invoked do |certname, options|
       Puppet::Face[:plugin, '0.0.1'].download