Merge remote-tracking branch 'remotes/lak/tickets/next/7118-summaries_for_all_faces' into 2.7.x

Fix conflicts due to version drift in:
	lib/puppet/face/certificate.rb
	lib/puppet/face/facts.rb
	lib/puppet/face/node.rb
	lib/puppet/face/secret_agent.rb
	spec/lib/puppet/face/basetest.rb
	spec/unit/face/help_spec.rb

Reviewed-By: Markus Roberts <markus@puppetlabs.com>

15 files changed, 51 insertions, 15 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 4c2950fb3..9ee83d0a2 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 "provide access to the CA for certificate management"
+
   option "--ca-location LOCATION" do
     before_action do |action, args, options|
       Puppet::SSL::Host.ca_location = options[:ca_location].to_sym
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/facts.rb b/lib/puppet/face/facts.rb
index 04eab93a5..a5a279ddf 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."
+
   # Upload our facts to the server
   action(:upload) do
     render_as :yaml
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 12336df8f..7032debc3 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -1,3 +1,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."
 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/secret_agent.rb b/lib/puppet/face/secret_agent.rb
index e2714122d..a911467f8 100644
--- a/lib/puppet/face/secret_agent.rb
+++ b/lib/puppet/face/secret_agent.rb
@@ -1,6 +1,8 @@
 require 'puppet/face'
 
 Puppet::Face.define(:secret_agent, '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/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