(#6962) Add 'description' to faces and action.

This adds the 'description' method to the faces and actions, as well as
structured testing to ensure that the DSL works as expected.

Reviewed-By: Max Martin <max@puppetlabs.com>

5 files changed, 65 insertions, 44 deletions

diff --git a/lib/puppet/interface.rb b/lib/puppet/interface.rb
index 4a36b509a..d97e462de 100644
--- a/lib/puppet/interface.rb
+++ b/lib/puppet/interface.rb
@@ -68,9 +68,14 @@ class Puppet::Interface
     self.default_format = format.to_sym
   end
 
-  attr_accessor :summary
+  ########################################################################
+  # 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)
-    value.nil? or summary = value
+    self.summary = value unless value.nil?
     @summary
   end
   def summary=(value)
@@ -81,6 +86,13 @@ class Puppet::Interface
     @summary = value
   end
 
+  def description(value = nil)
+    self.description = value unless value.nil?
+    @description
+  end
+
+
+  ########################################################################
   attr_reader :name, :version
 
   def initialize(name, version, &block)
diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb
index d2d4facaa..860ce4058 100644
--- a/lib/puppet/interface/action.rb
+++ b/lib/puppet/interface/action.rb
@@ -28,7 +28,7 @@ class Puppet::Interface::Action
 
   ########################################################################
   # Documentation stuff, whee!
-  attr_accessor :summary
+  attr_accessor :summary, :description
   def summary=(value)
     value = value.to_s
     value =~ /\n/ and
diff --git a/spec/shared_behaviours/documentation_on_faces.rb b/spec/shared_behaviours/documentation_on_faces.rb
new file mode 100644
index 000000000..effca678c
--- /dev/null
+++ b/spec/shared_behaviours/documentation_on_faces.rb
@@ -0,0 +1,35 @@
+# 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 }.not_to raise_error
+        subject.summary.should == text
+      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 }.not_to raise_error
+        subject.summary.should == text
+      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/
+      end
+    end
+
+    describe "#description" do
+      it "should accept a description" do
+        subject.description = "hello"
+        subject.description.should == "hello"
+      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"
+      end
+    end
+  end
+end
diff --git a/spec/unit/interface/action_spec.rb b/spec/unit/interface/action_spec.rb
index 602e51314..72f1cca73 100755
--- a/spec/unit/interface/action_spec.rb
+++ b/spec/unit/interface/action_spec.rb
@@ -349,31 +349,12 @@ describe Puppet::Interface::Action do
     end
   end
 
-  context "documentation" do
+  it_should_behave_like "documentation on faces" do
     subject do
       face = Puppet::Interface.new(:action_documentation, '0.0.1') do
         action :documentation do end
       end
       face.get_action(:documentation)
     end
-
-    describe "#summary" do
-      it "should accept a summary" do
-        text = "this is my summary"
-        expect { subject.summary = text }.not_to raise_error
-        subject.summary.should == text
-      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 }.not_to raise_error
-        subject.summary.should == text
-      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/
-      end
-    end
   end
 end
diff --git a/spec/unit/interface_spec.rb b/spec/unit/interface_spec.rb
index 036372e6a..50ae9c711 100755
--- a/spec/unit/interface_spec.rb
+++ b/spec/unit/interface_spec.rb
@@ -33,7 +33,7 @@ describe Puppet::Interface do
 
   describe "#define" do
     it "should register the face" do
-      face = subject.define(:face_test_register, '0.0.1')
+      face  = subject.define(:face_test_register, '0.0.1')
       face.should == subject[:face_test_register, '0.0.1']
     end
 
@@ -50,6 +50,18 @@ describe Puppet::Interface do
       subject.new(:foo, '1.0.0').should respond_to(:summary).with(0).arguments
       subject.new(:foo, '1.0.0').should respond_to(:summary=).with(1).arguments
     end
+
+    # Required documentation methods...
+    { :summary     => "summary",
+      :description => "This is the description of the stuff\n\nWhee"
+    }.each do |attr, value|
+      it "should support #{attr} in the builder" do
+        face = subject.new(:builder, '1.0.0') do
+          self.send(attr, value)
+        end
+        face.send(attr).should == value
+      end
+    end
   end
 
   describe "#initialize" do
@@ -187,28 +199,9 @@ describe Puppet::Interface do
     end
   end
 
-  context "documentation" do
+  it_should_behave_like "documentation on faces" do
     subject do
       Puppet::Interface.new(:face_documentation, '0.0.1')
     end
-
-    describe "#summary" do
-      it "should accept a summary" do
-        text = "this is my summary"
-        expect { subject.summary = text }.not_to raise_error
-        subject.summary.should == text
-      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 }.not_to raise_error
-        subject.summary.should == text
-      end
-
-      it "should reject a summary with a newline" do
-        expect { subject.summary = "with \n embedded \n newlines" }.
-          to raise_error ArgumentError, /summary should be a single line/
-      end
-    end
   end
 end