(7118) Adding summaries for all faces

It's usually just a one-liner, but when I saw an
obvious opportunity for longer docs, I've added a
@longdocs variable that can be converted to longer
forms when ready.

Signed-off-by: Luke Kanies <luke@puppetlabs.com>

18 files changed, 69 insertions, 18 deletions

diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 0dcde3591..59356d43f 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -1,6 +1,15 @@
 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'."
+
   action(:apply) do
     when_invoked do |catalog, options|
       report = Puppet::Transaction::Report.new("apply")
diff --git a/lib/puppet/face/certificate.rb b/lib/puppet/face/certificate.rb
index 77e80f099..5f410fa4c 100644
--- a/lib/puppet/face/certificate.rb
+++ b/lib/puppet/face/certificate.rb
@@ -2,6 +2,8 @@ require 'puppet/face/indirector'
 require 'puppet/ssl/host'
 
 Puppet::Face::Indirector.define(:certificate, '0.0.1') do
+  summary "Manage certificates, including signing and revoking them."
+
   # REVISIT: This should use a pre-invoke hook to run the common code that
   # needs to happen before we invoke any action; that would be much nicer than
   # the "please repeat yourself" stuff found in here right now.
diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb
index 1feba25ab..4e711b25b 100644
--- a/lib/puppet/face/certificate_request.rb
+++ b/lib/puppet/face/certificate_request.rb
@@ -1,4 +1,5 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:certificate_request, '0.0.1') do
+  summary "Manage certificate requests."
 end
diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb
index 6a75aa578..f111586af 100644
--- a/lib/puppet/face/certificate_revocation_list.rb
+++ b/lib/puppet/face/certificate_revocation_list.rb
@@ -1,4 +1,5 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:certificate_revocation_list, '0.0.1') do
+  summary "Manage the list of revoked certificates."
 end
diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb
index 45cb6b156..d1f6d5a9e 100644
--- a/lib/puppet/face/config.rb
+++ b/lib/puppet/face/config.rb
@@ -1,6 +1,8 @@
 require 'puppet/face'
 
 Puppet::Face.define(:config, '0.0.1') do
+  summary "Interact with Puppet configuration options."
+
   action(:print) do
     when_invoked do |*args|
       options = args.pop
diff --git a/lib/puppet/face/configurer.rb b/lib/puppet/face/configurer.rb
index 74dfb854e..7aebc8da2 100644
--- a/lib/puppet/face/configurer.rb
+++ b/lib/puppet/face/configurer.rb
@@ -1,6 +1,8 @@
 require 'puppet/face'
 
 Puppet::Face.define(:configurer, '0.0.1') do
+  summary "Provides agent-like behavior, with no plugin downloading or reporting."
+
   action(:synchronize) do
     when_invoked do |certname, options|
       facts = Puppet::Face[:facts, '0.0.1'].find(certname)
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index 8668b2531..caa3cfd54 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -2,6 +2,8 @@ require 'puppet/face/indirector'
 require 'puppet/node/facts'
 
 Puppet::Face::Indirector.define(:facts, '0.0.1') do
+  summary "Retrieve, store, and view facts."
+
   set_default_format :yaml
 
   # Upload our facts to the server
diff --git a/lib/puppet/face/file.rb b/lib/puppet/face/file.rb
index 1aa9462dd..547df3e4f 100644
--- a/lib/puppet/face/file.rb
+++ b/lib/puppet/face/file.rb
@@ -1,5 +1,7 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:file, '0.0.1') do
+  summary "Retrieve and store files in a filebucket"
+
   set_indirection_name :file_bucket_file
 end
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index 3a11ddb03..c85345167 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -1,4 +1,8 @@
 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'."
 end
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index fd1a548d6..b7ffaf38e 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -1,5 +1,10 @@
 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."
+
   set_default_format :yaml
 end
diff --git a/lib/puppet/face/parser.rb b/lib/puppet/face/parser.rb
index d4aaaf043..bea146f81 100644
--- a/lib/puppet/face/parser.rb
+++ b/lib/puppet/face/parser.rb
@@ -2,19 +2,21 @@ require 'puppet/face'
 require 'puppet/parser'
 
 Puppet::Face.define(:parser, '0.0.1') do
- action :validate do
-   when_invoked do |*args|
-     args.pop
-     files = args
-     if files.empty?
-       files << Puppet[:manifest]
-       Puppet.notice "No manifest specified. Validating the default manifest #{Puppet[:manifest]}"
-     end
-     files.each do |file|
-       Puppet[:manifest] = file
-       Puppet::Node::Environment.new(Puppet[:environment]).known_resource_types.clear
-     end
-     nil
-   end
- end
+  summary "Interact directly with the parser"
+
+  action :validate do
+    when_invoked do |*args|
+      args.pop
+      files = args
+      if files.empty?
+        files << Puppet[:manifest]
+        Puppet.notice "No manifest specified. Validating the default manifest #{Puppet[:manifest]}"
+      end
+      files.each do |file|
+        Puppet[:manifest] = file
+        Puppet::Node::Environment.new(Puppet[:environment]).known_resource_types.clear
+      end
+      nil
+    end
+  end
 end
diff --git a/lib/puppet/face/report.rb b/lib/puppet/face/report.rb
index 6e6f0b335..4de25ef92 100644
--- a/lib/puppet/face/report.rb
+++ b/lib/puppet/face/report.rb
@@ -1,6 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:report, '0.0.1') do
+  summary "Create, display, and submit reports"
+
   action(:submit) do
     when_invoked do |report, options|
       begin
diff --git a/lib/puppet/face/resource.rb b/lib/puppet/face/resource.rb
index d162f728a..908b2e462 100644
--- a/lib/puppet/face/resource.rb
+++ b/lib/puppet/face/resource.rb
@@ -1,4 +1,5 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:resource, '0.0.1') do
+  summary "Interact directly with resources via the RAL, like ralsh"
 end
diff --git a/lib/puppet/face/resource_type.rb b/lib/puppet/face/resource_type.rb
index 0cdbd719f..fe86eb873 100644
--- a/lib/puppet/face/resource_type.rb
+++ b/lib/puppet/face/resource_type.rb
@@ -1,4 +1,5 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:resource_type, '0.0.1') do
+  summary "View resource types, classes, and nodes from all manifests"
 end
diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb
index 7085e7cd7..2a0956ee3 100644
--- a/lib/puppet/face/status.rb
+++ b/lib/puppet/face/status.rb
@@ -1,4 +1,5 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:status, '0.0.1') do
+  summary "View status information"
 end
diff --git a/spec/lib/puppet/face/basetest.rb b/spec/lib/puppet/face/basetest.rb
index 00616f74f..9a658b685 100755
--- a/spec/lib/puppet/face/basetest.rb
+++ b/spec/lib/puppet/face/basetest.rb
@@ -1 +1,3 @@
-Puppet::Face.define(:basetest, '0.0.1')
+Puppet::Face.define(:basetest, '0.0.1') do
+  summary "This is just so tests don't fail"
+end
diff --git a/spec/unit/application/indirection_base_spec.rb b/spec/unit/application/indirection_base_spec.rb
index 63ab11eed..dedadb4ad 100755
--- a/spec/unit/application/indirection_base_spec.rb
+++ b/spec/unit/application/indirection_base_spec.rb
@@ -9,6 +9,7 @@ class Puppet::Application::TestIndirection < Puppet::Application::IndirectionBas
 end
 
 face = Puppet::Face::Indirector.define(:testindirection, '0.0.1') do
+  summary "fake summary"
 end
 # REVISIT: This horror is required because we don't allow anything to be
 # :current except for if it lives on, and is loaded from, disk. --daniel 2011-03-29
diff --git a/spec/unit/face/help_spec.rb b/spec/unit/face/help_spec.rb
index e67f29e07..33e13a240 100755
--- a/spec/unit/face/help_spec.rb
+++ b/spec/unit/face/help_spec.rb
@@ -46,6 +46,12 @@ describe Puppet::Face[:help, '0.0.1'] do
   context "when listing subcommands" do
     subject { Puppet::Face[:help, :current].help }
 
+    RSpec::Matchers.define :have_a_summary do
+      match do |instance|
+        instance.summary.is_a?(String)
+      end
+    end
+
     # Check a precondition for the next block; if this fails you have
     # something odd in your set of face, and we skip testing things that
     # matter. --daniel 2011-04-10
@@ -59,8 +65,13 @@ describe Puppet::Face[:help, '0.0.1'] do
       face = Puppet::Face[name, :current]
       summary = face.summary
 
-      it { should =~ %r{ #{name} } }
-      it { should =~ %r{ #{name} +#{summary}} } if summary
+      it "should list the '#{name}' face in the general help" do
+        should =~ %r{ #{name} }
+      end
+
+      it "should have a summary for #{name}" do
+        face.should have_a_summary
+      end
     end
 
     Puppet::Face[:help, :current].legacy_applications.each do |appname|