[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 e8eb290a1681baa19ef0b035af7cf17daadc6069
Author: Daniel Pittman <daniel at puppetlabs.com>
Date:   Wed Apr 27 10:05:48 2011 -0700

    (#6962) Finish documentation API on Face options.
    
    This extends the last of the documentation support, down into options, so they
    can be described as expected.  In the process we split out the modular docs
    API into a full and short version   options only want short docs, but the
    behaviours are identical to the full version.

diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb
index ba64d2b..07c3ed9 100644
--- a/lib/puppet/face/help.rb
+++ b/lib/puppet/face/help.rb
@@ -13,7 +13,7 @@ Puppet::Face.define(:help, '0.0.1') 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 7a9b871..c26958a 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -20,7 +20,8 @@ OPTIONS
 %   action.options.sort.each do |name|
 %     option = action.get_option name
 <%= "  " + option.optparse.join(" |" ) %>
-<%= option.desc and option.desc.gsub(/^/, '    ') %>
+<%= option.summary %>
+<%= option.description %>
 
 %   end
 % end
diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb
index 944f7a9..b249981 100644
--- a/lib/puppet/face/help/face.erb
+++ b/lib/puppet/face/help/face.erb
@@ -16,7 +16,8 @@ OPTIONS
 %   face.options.sort.each do |name|
 %     option = face.get_option name
 <%= "  " + option.optparse.join(" |" ) %>
-<%= option.desc and option.desc.gsub(/^/, '    ') %>
+<%= option.summary %>
+<%= option.description %>
 
 %   end
 % end
diff --git a/lib/puppet/face/indirector.rb b/lib/puppet/face/indirector.rb
index 6c7708b..a7ff7e1 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/interface.rb b/lib/puppet/interface.rb
index 23d760b..4a73506 100644
--- a/lib/puppet/interface.rb
+++ b/lib/puppet/interface.rb
@@ -4,7 +4,7 @@ require 'puppet/interface/documentation'
 require 'prettyprint'
 
 class Puppet::Interface
-  include DocSupport
+  include FullDocs
 
   require 'puppet/interface/face_collection'
 
diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb
index 18c7ab0..177df81 100644
--- a/lib/puppet/interface/action.rb
+++ b/lib/puppet/interface/action.rb
@@ -3,7 +3,7 @@ require 'puppet/interface/documentation'
 require 'prettyprint'
 
 class Puppet::Interface::Action
-  include Puppet::Interface::DocSupport
+  include Puppet::Interface::FullDocs
 
   def initialize(face, name, attrs = {})
     raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/
diff --git a/lib/puppet/interface/documentation.rb b/lib/puppet/interface/documentation.rb
index f3bf33d..d0bfbb2 100644
--- a/lib/puppet/interface/documentation.rb
+++ b/lib/puppet/interface/documentation.rb
@@ -1,5 +1,5 @@
 class Puppet::Interface
-  module DocSupport
+  module TinyDocs
     attr_accessor :summary
     def summary(value = nil)
       self.summary = value unless value.nil?
@@ -18,6 +18,10 @@ class Puppet::Interface
       self.description = value unless value.nil?
       @description
     end
+  end
+
+  module FullDocs
+    include TinyDocs
 
     attr_accessor :examples
     def examples(value = nil)
diff --git a/lib/puppet/interface/option.rb b/lib/puppet/interface/option.rb
index 3d3840f..493b5c3 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::FullDocs
+  # 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/shared_behaviours/things_that_declare_options.rb b/spec/shared_behaviours/things_that_declare_options.rb
index 5300a15..3d33bab 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 e934685..3e91c68 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

-- 
Puppet packaging for Debian