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