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

33 files changed, 698 insertions, 81 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
diff --git a/lib/puppet/interface.rb b/lib/puppet/interface.rb
index ba68ac65b..c7a167d3a 100644
--- a/lib/puppet/interface.rb
+++ b/lib/puppet/interface.rb
@@ -1,7 +1,11 @@
 require 'puppet'
 require 'puppet/util/autoload'
+require 'puppet/interface/documentation'
+require 'prettyprint'
 
 class Puppet::Interface
+  include FullDocs
+
   require 'puppet/interface/face_collection'
 
   require 'puppet/interface/action_manager'
@@ -65,27 +69,33 @@ class Puppet::Interface
     Puppet.warning("set_default_format is deprecated (and ineffective); use render_as on your actions instead.")
   end
 
+
   ########################################################################
   # Documentation.  We currently have to rewrite both getters because we share
   # the same instance between build-time and the runtime instance.  When that
   # splits out this should merge into a module that both the action and face
   # include. --daniel 2011-04-17
-  attr_accessor :summary, :description
-  def summary(value = nil)
-    self.summary = value unless value.nil?
-    @summary
-  end
-  def summary=(value)
-    value = value.to_s
-    value =~ /\n/ and
-      raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead."
-
-    @summary = value
-  end
-
-  def description(value = nil)
-    self.description = value unless value.nil?
-    @description
+  def synopsis
+    output = PrettyPrint.format do |s|
+      s.text("puppet #{name} <action>")
+      s.breakable
+
+      options.each do |option|
+        option = get_option(option)
+        wrap = option.required? ? %w{ < > } : %w{ [ ] }
+
+        s.group(0, *wrap) do
+          option.optparse.each do |item|
+            unless s.current_group.first?
+              s.breakable
+              s.text '|'
+              s.breakable
+            end
+            s.text item
+          end
+        end
+      end
+    end
   end
 
 
@@ -97,9 +107,15 @@ class Puppet::Interface
       raise ArgumentError, "Cannot create face #{name.inspect} with invalid version number '#{version}'!"
     end
 
-    @name = Puppet::Interface::FaceCollection.underscorize(name)
+    @name    = Puppet::Interface::FaceCollection.underscorize(name)
     @version = version
 
+    # The few bits of documentation we actually demand.  The default license
+    # is a favour to our end users; if you happen to get that in a core face
+    # report it as a bug, please. --daniel 2011-04-26
+    @authors  = []
+    @license  = 'All Rights Reserved'
+
     instance_eval(&block) if block_given?
   end
 
diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb
index 464b2a738..ac66d2946 100644
--- a/lib/puppet/interface/action.rb
+++ b/lib/puppet/interface/action.rb
@@ -1,12 +1,21 @@
-# -*- coding: utf-8 -*-
 require 'puppet/interface'
-require 'puppet/interface/option'
+require 'puppet/interface/documentation'
+require 'prettyprint'
 
 class Puppet::Interface::Action
+  include Puppet::Interface::FullDocs
+
   def initialize(face, name, attrs = {})
     raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/
     @face    = face
     @name    = name.to_sym
+
+    # The few bits of documentation we actually demand.  The default license
+    # is a favour to our end users; if you happen to get that in a core face
+    # report it as a bug, please. --daniel 2011-04-26
+    @authors = []
+    @license  = 'All Rights Reserved'
+
     attrs.each do |k, v| send("#{k}=", v) end
 
     @options        = {}
@@ -30,8 +39,31 @@ class Puppet::Interface::Action
     !!@default
   end
 
-  attr_accessor :summary
-
+  ########################################################################
+  # Documentation...
+  def synopsis
+    output = PrettyPrint.format do |s|
+      s.text("puppet #{@face.name}")
+      s.text(" #{name}") unless default?
+      s.breakable
+
+      options.each do |option|
+        option = get_option(option)
+        wrap = option.required? ? %w{ < > } : %w{ [ ] }
+
+        s.group(0, *wrap) do
+          option.optparse.each do |item|
+            unless s.current_group.first?
+              s.breakable
+              s.text '|'
+              s.breakable
+            end
+            s.text item
+          end
+        end
+      end
+    end
+  end
 
   ########################################################################
   # Support for rendering formats and all.
@@ -83,18 +115,6 @@ class Puppet::Interface::Action
 
 
   ########################################################################
-  # Documentation stuff, whee!
-  attr_accessor :summary, :description
-  def summary=(value)
-    value = value.to_s
-    value =~ /\n/ and
-      raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead."
-
-    @summary = value
-  end
-
-
-  ########################################################################
   # Initially, this was defined to allow the @action.invoke pattern, which is
   # a very natural way to invoke behaviour given our introspection
   # capabilities.   Heck, our initial plan was to have the faces delegate to
diff --git a/lib/puppet/interface/action_manager.rb b/lib/puppet/interface/action_manager.rb
index 440be2d1b..c5eb8e08a 100644
--- a/lib/puppet/interface/action_manager.rb
+++ b/lib/puppet/interface/action_manager.rb
@@ -1,9 +1,11 @@
-require 'puppet/interface/action_builder'
+require 'puppet/interface/action'
 
 module Puppet::Interface::ActionManager
   # Declare that this app can take a specific action, and provide
   # the code to do so.
   def action(name, &block)
+    require 'puppet/interface/action_builder'
+
     @actions ||= {}
     @default_action ||= nil
     raise "Action #{name} already defined for #{self}" if action?(name)
diff --git a/lib/puppet/interface/documentation.rb b/lib/puppet/interface/documentation.rb
new file mode 100644
index 000000000..d0bfbb261
--- /dev/null
+++ b/lib/puppet/interface/documentation.rb
@@ -0,0 +1,172 @@
+class Puppet::Interface
+  module TinyDocs
+    attr_accessor :summary
+    def summary(value = nil)
+      self.summary = value unless value.nil?
+      @summary
+    end
+    def summary=(value)
+      value = value.to_s
+      value =~ /\n/ and
+        raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead."
+
+      @summary = value
+    end
+
+    attr_accessor :description
+    def description(value = nil)
+      self.description = value unless value.nil?
+      @description
+    end
+  end
+
+  module FullDocs
+    include TinyDocs
+
+    attr_accessor :examples
+    def examples(value = nil)
+      self.examples = value unless value.nil?
+      @examples
+    end
+
+    attr_accessor :short_description
+    def short_description(value = nil)
+      self.short_description = value unless value.nil?
+      if @short_description.nil? then
+        return nil if @description.nil?
+        lines = @description.split("\n")
+        grab  = [5, lines.index('') || 5].min
+        @short_description = lines[0, grab].join("\n")
+      end
+      @short_description
+    end
+
+    def author(value = nil)
+      unless value.nil? then
+        unless value.is_a? String
+          raise ArgumentError, 'author must be a string; use multiple statements for multiple authors'
+        end
+
+        if value =~ /\n/ then
+          raise ArgumentError, 'author should be a single line; use multiple statements for multiple authors'
+        end
+        @authors.push(value)
+      end
+      @authors.empty? ? nil : @authors.join("\n")
+    end
+    def author=(value)
+      if Array(value).any? {|x| x =~ /\n/ } then
+        raise ArgumentError, 'author should be a single line; use multiple statements'
+      end
+      @authors = Array(value)
+    end
+    def authors
+      @authors
+    end
+    def authors=(value)
+      if Array(value).any? {|x| x =~ /\n/ } then
+        raise ArgumentError, 'author should be a single line; use multiple statements'
+      end
+      @authors = Array(value)
+    end
+
+    attr_accessor :notes
+    def notes(value = nil)
+      @notes = value unless value.nil?
+      @notes
+    end
+
+    attr_accessor :license
+    def license(value = nil)
+      @license = value unless value.nil?
+      @license
+    end
+
+    def copyright(owner = nil, years = nil)
+      if years.nil? and not owner.nil? then
+        raise ArgumentError, 'copyright takes the owners names, then the years covered'
+      end
+      self.copyright_owner = owner unless owner.nil?
+      self.copyright_years = years unless years.nil?
+
+      if self.copyright_years or self.copyright_owner then
+        "Copyright #{self.copyright_years} by #{self.copyright_owner}"
+      else
+        "Unknown copyright owner and years."
+      end
+    end
+
+    attr_accessor :copyright_owner
+    def copyright_owner=(value)
+      case value
+      when String then @copyright_owner = value
+      when Array  then @copyright_owner = value.join(", ")
+      else
+        raise ArgumentError, "copyright owner must be a string or an array of strings"
+      end
+      @copyright_owner
+    end
+
+    attr_accessor :copyright_years
+    def copyright_years=(value)
+      years = munge_copyright_year value
+      years = (years.is_a?(Array) ? years : [years]).
+        sort_by do |x| x.is_a?(Range) ? x.first : x end
+
+      @copyright_years = years.map do |year|
+        if year.is_a? Range then
+          "#{year.first}-#{year.last}"
+        else
+          year
+        end
+      end.join(", ")
+    end
+
+    def munge_copyright_year(input)
+      case input
+      when Range then input
+      when Integer then
+        if input < 1970 then
+          fault = "before 1970"
+        elsif input > (future = Time.now.year + 2) then
+          fault = "after #{future}"
+        end
+        if fault then
+          raise ArgumentError, "copyright with a year #{fault} is very strange; did you accidentally add or subtract two years?"
+        end
+
+        input
+
+      when String then
+        input.strip.split(/,/).map do |part|
+          part = part.strip
+          if part =~ /^\d+$/ then
+            part.to_i
+          elsif found = part.split(/-/) then
+            unless found.length == 2 and found.all? {|x| x.strip =~ /^\d+$/ }
+              raise ArgumentError, "#{part.inspect} is not a good copyright year or range"
+            end
+            Range.new(found[0].to_i, found[1].to_i)
+          else
+            raise ArgumentError, "#{part.inspect} is not a good copyright year or range"
+          end
+        end
+
+      when Array then
+        result = []
+        input.each do |item|
+          item = munge_copyright_year item
+          if item.is_a? Array
+            result.concat item
+          else
+            result << item
+          end
+        end
+        result
+
+      else
+        raise ArgumentError, "#{input.inspect} is not a good copyright year, set, or range"
+      end
+    end
+  end
+end
diff --git a/lib/puppet/interface/option.rb b/lib/puppet/interface/option.rb
index 3d3840ff6..b68bdeb12 100644
--- a/lib/puppet/interface/option.rb
+++ b/lib/puppet/interface/option.rb
@@ -1,6 +1,10 @@
 require 'puppet/interface'
 
 class Puppet::Interface::Option
+  include Puppet::Interface::TinyDocs
+  # For compatibility, deprecated, and should go fairly soon...
+  ['', '='].each { |x| alias :"desc#{x}" :"description#{x}" }
+
   def initialize(parent, *declaration, &block)
     @parent   = parent
     @optparse = []
@@ -80,7 +84,7 @@ class Puppet::Interface::Option
   end
 
   attr_reader   :parent, :name, :aliases, :optparse
-  attr_accessor :required, :desc
+  attr_accessor :required
 
   attr_accessor :before_action
   def before_action=(proc)
diff --git a/spec/integration/faces/documentation_spec.rb b/spec/integration/faces/documentation_spec.rb
new file mode 100755
index 000000000..9ddf2f1b3
--- /dev/null
+++ b/spec/integration/faces/documentation_spec.rb
@@ -0,0 +1,55 @@
+#!/usr/bin/env rspec
+require 'spec_helper'
+require 'puppet/face'
+
+describe "documentation of faces" do
+  it "should generate global help" do
+    help = nil
+    expect { help = Puppet::Face[:help, :current].help }.not_to raise_error
+    help.should be_an_instance_of String
+    help.length.should be > 200
+  end
+
+  ########################################################################
+  # Can we actually generate documentation for the face, and the actions it
+  # has?  This avoids situations where the ERB template turns out to have a
+  # bug in it, triggered in something the user might do.
+  Puppet::Face.faces.sort.each do |face_name|
+    # REVISIT: We should walk all versions of the face here...
+    let :help do Puppet::Face[:help, :current] end
+
+    context "generating help" do
+      it "for #{face_name}" do
+        expect {
+          text = help.help(face_name)
+          text.should be_an_instance_of String
+          text.length.should be > 100
+        }.not_to raise_error
+      end
+
+      Puppet::Face[face_name, :current].actions.sort.each do |action_name|
+        it "for #{face_name}.#{action_name}" do
+          expect {
+            text = help.help(face_name, action_name)
+            text.should be_an_instance_of String
+            text.length.should be > 100
+          }.not_to raise_error
+        end
+      end
+    end
+
+    ########################################################################
+    # Ensure that we have authorship and copyright information in *our* faces;
+    # if you apply this to third party faces you might well be disappointed.
+    context "licensing of Puppet Labs face '#{face_name}'" do
+      subject { Puppet::Face[face_name, :current] }
+      its :license   do should =~ /Apache\s*2/ end
+      its :copyright do should =~ /Puppet Labs/ end
+
+      # REVISIT: This is less that ideal, I think, but right now I am more
+      # comfortable watching us ship with some copyright than without any; we
+      # can redress that when it becomes appropriate. --daniel 2011-04-27
+      its :copyright do should =~ /2011/ end
+    end
+  end
+end
diff --git a/spec/lib/puppet/face/basetest.rb b/spec/lib/puppet/face/basetest.rb
index a98bc382f..41a4ef3f9 100755
--- a/spec/lib/puppet/face/basetest.rb
+++ b/spec/lib/puppet/face/basetest.rb
@@ -1,6 +1,8 @@
 require 'puppet/face'
 
 Puppet::Face.define(:basetest, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
   summary "This is just so tests don't fail"
 
   option "--[no-]boolean"
diff --git a/spec/lib/puppet/face/huzzah.rb b/spec/lib/puppet/face/huzzah.rb
index 3428c6816..2c2b7aa8d 100755
--- a/spec/lib/puppet/face/huzzah.rb
+++ b/spec/lib/puppet/face/huzzah.rb
@@ -1,5 +1,7 @@
 require 'puppet/face'
 Puppet::Face.define(:huzzah, '2.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
   summary "life is a thing for celebration"
   action :bar do "is where beer comes from" end
 end
diff --git a/spec/lib/puppet/face/version_matching.rb b/spec/lib/puppet/face/version_matching.rb
index bfd0013f7..52bc71dbd 100644
--- a/spec/lib/puppet/face/version_matching.rb
+++ b/spec/lib/puppet/face/version_matching.rb
@@ -4,6 +4,8 @@ require 'puppet/face'
 # change this you need to ensure that is still correct. --daniel 2011-04-21
 ['1.0.0', '1.0.1', '1.1.0', '1.1.1', '2.0.0'].each do |version|
   Puppet::Face.define(:version_matching, version) do
+    copyright "Puppet Labs", 2011
+    license   "Apache 2 license; see COPYING"
     summary "version matching face #{version}"
     script :version do version end
   end
diff --git a/spec/shared_behaviours/documentation_on_faces.rb b/spec/shared_behaviours/documentation_on_faces.rb
index 41b4015c9..dd2bd3110 100644
--- a/spec/shared_behaviours/documentation_on_faces.rb
+++ b/spec/shared_behaviours/documentation_on_faces.rb
@@ -1,34 +1,216 @@
 # encoding: UTF-8
 shared_examples_for "documentation on faces" do
-  context "description" do
-    describe "#summary" do
-      it "should accept a summary" do
-        text = "this is my summary"
-        expect { subject.summary = text }.to_not raise_error
-        subject.summary.should == text
+  defined?(Attrs) or
+    Attrs = [:summary, :description, :examples, :short_description, :notes, :author]
+
+  defined?(SingleLineAttrs) or
+    SingleLineAttrs = [:summary, :author]
+
+  # Simple, procedural tests that apply to a bunch of methods.
+  Attrs.each do |attr|
+    it "should accept a #{attr}" do
+      expect { subject.send("#{attr}=", "hello") }.not_to raise_error
+      subject.send(attr).should == "hello"
+    end
+
+    it "should accept a long (single line) value for #{attr}" do
+      text = "I never know when to stop with the word banana" + ("na" * 1000)
+      expect { subject.send("#{attr}=", text) }.to_not raise_error
+      subject.send(attr).should == text
+    end
+  end
+
+  # Should they accept multiple lines?
+  Attrs.each do |attr|
+    text = "with\nnewlines"
+
+    if SingleLineAttrs.include? attr then
+      it "should not accept multiline values for #{attr}" do
+        expect { subject.send("#{attr}=", text) }.
+          to raise_error ArgumentError, /#{attr} should be a single line/
+        subject.send(attr).should be_nil
+      end
+    else
+      it "should accept multiline values for #{attr}" do
+        expect { subject.send("#{attr}=", text) }.not_to raise_error
+        subject.send(attr).should == text
+      end
+    end
+  end
+
+  describe "#short_description" do
+    it "should return the set value if set after description" do
+      subject.description = "hello\ngoodbye"
+      subject.short_description = "whatever"
+      subject.short_description.should == "whatever"
+    end
+
+    it "should return the set value if set before description" do
+      subject.short_description = "whatever"
+      subject.description = "hello\ngoodbye"
+      subject.short_description.should == "whatever"
+    end
+
+    it "should return nothing if not set and no description" do
+      subject.short_description.should be_nil
+    end
+
+    it "should return the first paragraph of description if not set (where it is one line long)" do
+      subject.description = "hello"
+      subject.short_description.should == subject.description
+    end
+
+    it "should return the first paragraph of description if not set (where there is no paragraph break)" do
+      subject.description = "hello\ngoodbye"
+      subject.short_description.should == subject.description
+    end
+
+    it "should return the first paragraph of description if not set (where there is a paragraph break)" do
+      subject.description = "hello\ngoodbye\n\nmore\ntext\nhere\n\nfinal\nparagraph"
+      subject.short_description.should == "hello\ngoodbye"
+    end
+
+    it "should trim a very, very long first paragraph" do
+      line = "this is a very, very, very long long line full of text\n"
+      subject.description = line * 20 + "\n\nwhatever, dude."
+
+      subject.short_description.should == (line * 5).chomp
+    end
+  end
+
+  describe "multiple authors" do
+    authors = %w{John Paul George Ringo}
+
+    context "in the DSL" do
+      it "should support multiple authors" do
+
+        authors.each {|name| subject.author name }
+        subject.authors.should =~ authors
+
+        subject.author.should == authors.join("\n")
+      end
+
+      it "should reject author as an array" do
+        expect { subject.author ["Foo", "Bar"] }.
+          to raise_error ArgumentError, /author must be a string/
+      end
+    end
+
+    context "#author=" do
+      it "should accept a single name" do
+        subject.author = "Fred"
+        subject.author.should == "Fred"
       end
 
-      it "should accept a long, long, long summary" do
-        text = "I never know when to stop with the word banana" + ("na" * 1000)
-        expect { subject.summary = text }.to_not raise_error
-        subject.summary.should == text
+      it "should accept an array of names" do
+        subject.author = authors
+        subject.authors.should =~ authors
+        subject.author.should == authors.join("\n")
+      end
+
+      it "should not append when set multiple times" do
+        subject.author = "Fred"
+        subject.author = "John"
+        subject.author.should == "John"
+      end
+
+      it "should reject arrays with embedded newlines" do
+        expect { subject.author = ["Fred\nJohn"] }.
+          to raise_error ArgumentError, /author should be a single line/
+      end
+    end
+  end
+
+  describe "#license" do
+    it "should default to reserving rights" do
+      subject.license.should =~ /All Rights Reserved/
+    end
+
+    it "should accept an arbitrary license string on the object" do
+      subject.license = "foo"
+      subject.license.should == "foo"
+    end
+
+    it "should accept symbols to specify existing licenses..."
+  end
+
+  describe "#copyright" do
+    it "should fail with just a name" do
+      expect { subject.copyright("invalid") }.
+        to raise_error ArgumentError, /copyright takes the owners names, then the years covered/
+    end
+
+    [1997, "1997"].each do |year|
+      it "should accept an entity name and a #{year.class.name} year" do
+        subject.copyright("me", year)
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /#{year}/
       end
 
-      it "should reject a summary with a newline" do
-        expect { subject.summary = "with\nnewlines" }.
-          to raise_error ArgumentError, /summary should be a single line/
+      it "should accept multiple entity names and a #{year.class.name} year" do
+        subject.copyright ["me", "you"], year
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /\byou\b/
+        subject.copyright.should =~ /#{year}/
       end
     end
 
-    describe "#description" do
-      it "should accept a description" do
-        subject.description = "hello"
-        subject.description.should == "hello"
+    ["1997-2003", "1997 - 2003", 1997..2003].each do |range|
+      it "should accept a #{range.class.name} range of years" do
+        subject.copyright("me", range)
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /1997-2003/
+      end
+
+      it "should accept a #{range.class.name} range of years" do
+        subject.copyright ["me", "you"], range
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /\byou\b/
+        subject.copyright.should =~ /1997-2003/
+      end
+    end
+
+    [[1997, 2003], ["1997", 2003], ["1997", "2003"]].each do |input|
+      it "should accept the set of years #{input.inspect} in an array" do
+        subject.copyright "me", input
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /1997, 2003/
+      end
+
+      it "should accept the set of years #{input.inspect} in an array" do
+        subject.copyright ["me", "you"], input
+        subject.copyright.should =~ /\bme\b/
+        subject.copyright.should =~ /\byou\b/
+        subject.copyright.should =~ /1997, 2003/
+      end
+    end
+
+    it "should warn if someone does math accidentally on the range of years" do
+      expect { subject.copyright "me", 1997-2003 }.
+        to raise_error ArgumentError, /copyright with a year before 1970 is very strange; did you accidentally add or subtract two years\?/
+    end
+
+    it "should accept complex copyright years" do
+      years = [1997, 1999, 2000..2002, 2005].reverse
+      subject.copyright "me", years
+      subject.copyright.should =~ /\bme\b/
+      subject.copyright.should =~ /1997, 1999, 2000-2002, 2005/
+    end
+  end
+
+  # Things that are automatically generated.
+  [:name, :options, :synopsis].each do |attr|
+    describe "##{attr}" do
+      it "should not allow you to set #{attr}" do
+        subject.should_not respond_to :"#{attr}="
+      end
+
+      it "should have a #{attr}" do
+        subject.send(attr).should_not be_nil
       end
 
-      it "should accept a description with a newline" do
-        subject.description = "hello \n my \n fine \n friend"
-        subject.description.should == "hello \n my \n fine \n friend"
+      it "'s #{attr} should not be empty..." do
+        subject.send(attr).should_not == ''
       end
     end
   end
diff --git a/spec/shared_behaviours/things_that_declare_options.rb b/spec/shared_behaviours/things_that_declare_options.rb
index 5300a159a..3d33bab7f 100755
--- a/spec/shared_behaviours/things_that_declare_options.rb
+++ b/spec/shared_behaviours/things_that_declare_options.rb
@@ -28,6 +28,8 @@ shared_examples_for "things that declare options" do
     thing = add_options_to do
       option "--foo" do
         desc text
+        description text
+        summary text
       end
     end
 
diff --git a/spec/unit/interface/option_builder_spec.rb b/spec/unit/interface/option_builder_spec.rb
index e9346852c..3e91c683b 100755
--- a/spec/unit/interface/option_builder_spec.rb
+++ b/spec/unit/interface/option_builder_spec.rb
@@ -16,13 +16,15 @@ describe Puppet::Interface::OptionBuilder do
     option.should be_an_instance_of Puppet::Interface::Option
   end
 
-  it "should support documentation declarations" do
-    text = "this is the description"
-    option = Puppet::Interface::OptionBuilder.build(face, "--foo") do
-      desc text
+  [:description, :summary].each do |doc|
+    it "should support #{doc} declarations" do
+      text = "this is the #{doc}"
+      option = Puppet::Interface::OptionBuilder.build(face, "--foo") do
+        self.send doc, text
+      end
+      option.should be_an_instance_of Puppet::Interface::Option
+      option.send(doc).should == text
     end
-    option.should be_an_instance_of Puppet::Interface::Option
-    option.desc.should == text
   end
 
   context "before_action hook" do
diff --git a/spec/unit/interface_spec.rb b/spec/unit/interface_spec.rb
index a1d70cf64..27da39766 100755
--- a/spec/unit/interface_spec.rb
+++ b/spec/unit/interface_spec.rb
@@ -76,7 +76,11 @@ describe Puppet::Interface do
 
     # Required documentation methods...
     { :summary     => "summary",
-      :description => "This is the description of the stuff\n\nWhee"
+      :description => "This is the description of the stuff\n\nWhee",
+      :examples    => "This is my example",
+      :short_description => "This is my custom short description",
+      :notes       => "These are my notes...",
+      :author      => "This is my authorship data",
     }.each do |attr, value|
       it "should support #{attr} in the builder" do
         face = subject.new(:builder, '1.0.0') do