[Pkg-puppet-devel] [SCM] Puppet packaging for Debian branch, experimental, updated. debian/2.6.8-1-844-g7ec39d5

[Daniel Pittman]

The following commit has been merged in the experimental branch:
commit ebf49f98357f93b33e09c0ecbdee1c5c2db87569
Merge: 1aaf5fdc51e165c7d0f377450016cd4fb3767c02 0256d67e1a51a37f2c87ec197bdff6ef3a6b269f
Author: Daniel Pittman <daniel at puppetlabs.com>
Date:   Wed Apr 27 12:12:05 2011 -0700

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

diff --combined lib/puppet/interface.rb
index ba68ac6,4a73506..c7a167d
--- a/lib/puppet/interface.rb
+++ b/lib/puppet/interface.rb
@@@ -1,7 -1,11 +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 +69,33 @@@
      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 +107,15 @@@
        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
  
@@@ -139,10 -155,12 +155,10 @@@
        action.get_option(name).__decoration_name(type)
      end
  
 +    # Exceptions here should propagate up; this implements a hook we can use
 +    # reasonably for option validation.
      methods.each do |hook|
 -      begin
 -        respond_to? hook and self.__send__(hook, action, passed_args, passed_options)
 -      rescue => e
 -        Puppet.warning("invoking #{action} #{type} hook: #{e}")
 -      end
 +      respond_to? hook and self.__send__(hook, action, passed_args, passed_options)
      end
    end
  
diff --combined lib/puppet/interface/action.rb
index 464b2a7,177df81..ac66d29
--- a/lib/puppet/interface/action.rb
+++ b/lib/puppet/interface/action.rb
@@@ -1,12 -1,21 +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 +39,31 @@@
      !!@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 +115,6 @@@
  
  
    ########################################################################
-   # 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
@@@ -239,7 -259,7 +259,7 @@@ WRAPPE
      end.select(&:required?).collect(&:name) - args.last.keys
  
      return if required.empty?
 -    raise ArgumentError, "missing required options (#{required.join(', ')})"
 +    raise ArgumentError, "The following options are required: #{required.join(', ')}"
    end
  
    ########################################################################

-- 
Puppet packaging for Debian