(#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.

10 files changed, 31 insertions, 15 deletions

diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb
index ba64d2b54..07c3ed9b1 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 7a9b87117..c26958a35 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 944f7a96b..b249981de 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 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/interface.rb b/lib/puppet/interface.rb
index 23d760b30..4a735069f 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 18c7ab057..177df81f2 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 f3bf33da5..d0bfbb261 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 3d3840ff6..493b5c3bd 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 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