Merge branch 'feature/2.7.x/6962-finish-documentation-api-for-faces' into 2.7.x

20 files changed, 171 insertions, 19 deletions

diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 59356d43f..98f550413 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -1,16 +1,23 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:catalog, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   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 +39,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/certificate.rb b/lib/puppet/face/certificate.rb
index 9ee83d0a2..7f2998da2 100644
--- a/lib/puppet/face/certificate.rb
+++ b/lib/puppet/face/certificate.rb
@@ -2,6 +2,9 @@ require 'puppet/face/indirector'
 require 'puppet/ssl/host'
 
 Puppet::Face::Indirector.define(:certificate, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "provide access to the CA for certificate management"
 
   option "--ca-location LOCATION" do
diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb
index 4e711b25b..0f7f72205 100644
--- a/lib/puppet/face/certificate_request.rb
+++ b/lib/puppet/face/certificate_request.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:certificate_request, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Manage certificate requests."
 end
diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb
index f111586af..9a8fe303d 100644
--- a/lib/puppet/face/certificate_revocation_list.rb
+++ b/lib/puppet/face/certificate_revocation_list.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:certificate_revocation_list, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Manage the list of revoked certificates."
 end
diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb
index d1f6d5a9e..fc685202c 100644
--- a/lib/puppet/face/config.rb
+++ b/lib/puppet/face/config.rb
@@ -1,6 +1,9 @@
 require 'puppet/face'
 
 Puppet::Face.define(:config, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Interact with Puppet configuration options."
 
   action(:print) do
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index a5a279ddf..88e3c7ba9 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -2,10 +2,14 @@ require 'puppet/face/indirector'
 require 'puppet/node/facts'
 
 Puppet::Face::Indirector.define(:facts, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   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/file.rb b/lib/puppet/face/file.rb
index 547df3e4f..1b2e62b6d 100644
--- a/lib/puppet/face/file.rb
+++ b/lib/puppet/face/file.rb
@@ -1,6 +1,9 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:file, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Retrieve and store files in a filebucket"
 
   set_indirection_name :file_bucket_file
diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb
index a762fb02e..07c3ed9b1 100644
--- a/lib/puppet/face/help.rb
+++ b/lib/puppet/face/help.rb
@@ -4,13 +4,16 @@ require 'pathname'
 require 'erb'
 
 Puppet::Face.define(:help, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Displays help about puppet subcommands"
 
   action(:help) do
     summary "Display help about faces and their actions."
 
     option "--version VERSION" do
-      desc "Which version of the interface to show help for"
+      summary "which version of the interface to show help for"
     end
 
     default
diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb
index eaf131464..c26958a35 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -1,3 +1,48 @@
-Use: puppet <%= face.name %> [options] <%= action.name %> [options]
+puppet <%= face.name %><%= action.default? ? '' : " #{action.name}" %>(1) -- <%= action.summary || face.summary %>
+<%= '=' * (_erbout.length - 1) %>
 
-Summary: <%= action.summary %>
+% if action.synopsis
+SYNOPSIS
+--------
+
+<%= action.synopsis %>
+
+% end
+% if action.description
+DESCRIPTION
+-----------
+<%= action.description %>
+
+%end
+% unless action.options.empty?
+OPTIONS
+-------
+%   action.options.sort.each do |name|
+%     option = action.get_option name
+<%= "  " + option.optparse.join(" |" ) %>
+<%= option.summary %>
+<%= option.description %>
+
+%   end
+% end
+% if action.examples
+EXAMPLES
+--------
+<%= action.examples %>
+% end
+% if action.notes
+NOTES
+-----
+<%= action.notes %>
+
+% end
+% unless action.authors.empty?
+AUTHOR
+------
+<%= action.authors.map {|x| " * " + x } .join("\n") %>
+
+%end
+COPYRIGHT AND LICENSE
+---------------------
+<%= action.copyright %>
+<%= action.license   %>
diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb
index efe5fd809..b249981de 100644
--- a/lib/puppet/face/help/face.erb
+++ b/lib/puppet/face/help/face.erb
@@ -1,7 +1,48 @@
-Use: puppet <%= face.name %> [options] <action> [options]
+NAME
+  <%= face.name %> -- <%= face.summary || "unknown face..." %>
 
-Available actions:
+% if face.synopsis
+SYNOPSIS
+<%= face.synopsis.gsub(/^/, '  ') %>
+
+% end
+% if face.description
+DESCRIPTION
+<%= face.description.chomp.gsub(/^/, '  ') %>
+
+%end
+% unless face.options.empty?
+OPTIONS
+%   face.options.sort.each do |name|
+%     option = face.get_option name
+<%= "  " + option.optparse.join(" |" ) %>
+<%= option.summary %>
+<%= option.description %>
+
+%   end
+% end
+ACTIONS
+% padding = face.actions.map{|x| x.to_s.length}.max + 2
 % face.actions.each do |actionname|
 %   action = face.get_action(actionname)
-  <%= action.name.to_s.ljust(16) %>  <%= action.summary %>
+  <%= action.name.to_s.ljust(padding) %>  <%= action.summary %>
 % end
+
+% if face.examples
+EXAMPLES
+<%= face.examples %>
+% end
+% if face.notes
+NOTES
+<%= face.notes %>
+
+% end
+% unless face.authors.empty?
+AUTHOR
+<%= face.authors.join("\n").gsub(/^/, ' * ') %>
+
+%end
+COPYRIGHT AND LICENSE
+<%= face.copyright.gsub(/^/, '  ') %>
+<%= face.license.gsub(/^/, '  ')   %>
+
diff --git a/lib/puppet/face/indirector.rb b/lib/puppet/face/indirector.rb
index 6c7708b51..a7ff7e1f0 100644
--- a/lib/puppet/face/indirector.rb
+++ b/lib/puppet/face/indirector.rb
@@ -3,8 +3,10 @@ require 'puppet/face'
 
 class Puppet::Face::Indirector < Puppet::Face
   option "--terminus TERMINUS" do
-    desc "REVISIT: You can select a terminus, which has some bigger effect
-that we should describe in this file somehow."
+    description %q{
+REVISIT: You can select a terminus, which has some bigger effect
+that we should describe in this file somehow.
+}.strip
 
     before_action do |action, args, options|
       set_terminus(options[:terminus])
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index c85345167..5d1a9ab26 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -1,8 +1,14 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:key, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   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..3591dd92b 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -1,7 +1,11 @@
 require 'puppet/face/indirector'
 Puppet::Face::Indirector.define(:node, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   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/parser.rb b/lib/puppet/face/parser.rb
index bea146f81..c4c3fb55e 100644
--- a/lib/puppet/face/parser.rb
+++ b/lib/puppet/face/parser.rb
@@ -2,6 +2,9 @@ require 'puppet/face'
 require 'puppet/parser'
 
 Puppet::Face.define(:parser, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Interact directly with the parser"
 
   action :validate do
diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb
index 4d95bd93b..19060942a 100644
--- a/lib/puppet/face/plugin.rb
+++ b/lib/puppet/face/plugin.rb
@@ -1,5 +1,8 @@
 require 'puppet/face'
 Puppet::Face.define(:plugin, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Interact with the Puppet plugin system"
 
   action :download do
diff --git a/lib/puppet/face/report.rb b/lib/puppet/face/report.rb
index 4de25ef92..9855f3d2d 100644
--- a/lib/puppet/face/report.rb
+++ b/lib/puppet/face/report.rb
@@ -1,6 +1,9 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:report, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Create, display, and submit reports"
 
   action(:submit) do
diff --git a/lib/puppet/face/resource.rb b/lib/puppet/face/resource.rb
index 908b2e462..55a14f280 100644
--- a/lib/puppet/face/resource.rb
+++ b/lib/puppet/face/resource.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:resource, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   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 fe86eb873..8776dc105 100644
--- a/lib/puppet/face/resource_type.rb
+++ b/lib/puppet/face/resource_type.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:resource_type, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   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 af7ffb7b7..50018cb13 100644
--- a/lib/puppet/face/secret_agent.rb
+++ b/lib/puppet/face/secret_agent.rb
@@ -1,9 +1,14 @@
 require 'puppet/face'
 
 Puppet::Face.define(:secret_agent, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   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
 
diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb
index 2a0956ee3..d35d7e1b3 100644
--- a/lib/puppet/face/status.rb
+++ b/lib/puppet/face/status.rb
@@ -1,5 +1,8 @@
 require 'puppet/face/indirector'
 
 Puppet::Face::Indirector.define(:status, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "View status information"
 end