Add support for resource action descriptions

This will allow us to generate better documentation by including
action descriptions in the resource help, and includes updates to the
resource inspector and doc generation task to include action descriptions
in resource action data.

This change permits actions to be defined with the optional new
'description' parameter as follows:

```
action :my_action, description: "my_action changes the state of this world"
...
end

Action description can be looked up using the
`.action_description(action)` method of the resource class.  Action
descriptions are inheritable and overridable.

Signed-off-by: Marc A. Paradise <marc.paradise@gmail.com>

3 files changed, 67 insertions, 2 deletions

diff --git a/spec/integration/recipes/resource_action_spec.rb b/spec/integration/recipes/resource_action_spec.rb
index 9bfe86c74e..febac64283 100644
--- a/spec/integration/recipes/resource_action_spec.rb
+++ b/spec/integration/recipes/resource_action_spec.rb
@@ -223,6 +223,10 @@ module ResourceActionSpec
           ActionJackson.succeeded = ActionJackson.ruby_block_converged
         end
 
+        action :test1, description: "Original description" do
+          true
+        end
+
         def foo_public
           "foo_public!"
         end
@@ -293,7 +297,12 @@ module ResourceActionSpec
             ActionJackalope.jackalope_ran = :access_attribute
             ActionJackalope.succeeded = ActionJackson.succeeded
           end
+
+          action :test1, description: "An old action with a new description" do
+            super
+          end
         end
+
         before do
           ActionJackalope.jackalope_ran = nil
           ActionJackalope.load_current_resource_ran = nil
@@ -344,6 +353,11 @@ module ResourceActionSpec
           expect(ActionJackalope.succeeded).to eq "foo!alope blarghle! bar!alope"
         end
 
+        it "allows overridden action to have a description separate from the action defined in the base resource" do
+          expect(ActionJackson.action_description(:test1)).to eql "Original description"
+          expect(ActionJackalope.action_description(:test1)).to eql "An old action with a new description"
+        end
+
         it "non-overridden actions run and can access overridden and non-overridden variables (but not necessarily new ones)" do
           converge do
             action_jackalope "hi" do
diff --git a/spec/unit/resource_inspector_spec.rb b/spec/unit/resource_inspector_spec.rb
index f3a4b2aa0a..f786018b29 100644
--- a/spec/unit/resource_inspector_spec.rb
+++ b/spec/unit/resource_inspector_spec.rb
@@ -28,7 +28,11 @@ class DummyResource < Chef::Resource
   introduced "14.0"
   property :first, String, description: "My First Property", introduced: "14.0"
 
-  action :dummy do
+  action :dummy, description: "Dummy action" do
+    return true
+  end
+
+  action :dummy_no_desc do
     return true
   end
 end
@@ -39,7 +43,8 @@ describe Chef::ResourceInspector do
 
     it "returns a hash with required data" do
       expect(subject[:description]).to eq "A dummy resource"
-      expect(subject[:actions]).to match_array %i{nothing dummy}
+      expect(subject[:actions]).to eq({ nothing: nil, dummy: "Dummy action",
+                                        dummy_no_desc: nil })
     end
 
     context "excluding built in properties" do
diff --git a/spec/unit/resource_spec.rb b/spec/unit/resource_spec.rb
index 7a19e0e8e1..f7109cc680 100644
--- a/spec/unit/resource_spec.rb
+++ b/spec/unit/resource_spec.rb
@@ -1162,6 +1162,52 @@ describe Chef::Resource do
     end
   end
 
+  describe "#action_description" do
+    class TestResource < ::Chef::Resource
+      action :symbol_action, description: "a symbol test" do; end
+      action "string_action", description: "a string test" do; end
+      action :base_action0 do; end
+      action :base_action1, description: "unmodified base action 1 desc" do; end
+      action :base_action2, description: "unmodified base action 2 desc" do; end
+      action :base_action3, description: "unmodified base action 3 desc" do; end
+    end
+
+    it "returns nil when no description was provided for the action" do
+      expect(TestResource.action_description(:base_action0)).to eql(nil)
+    end
+
+    context "when action definition is a string" do
+      it "returns the description whether a symbol or string is used to look it up" do
+        expect(TestResource.action_description("string_action")).to eql("a string test")
+        expect(TestResource.action_description(:string_action)).to eql("a string test")
+      end
+    end
+
+    context "when action definition is a symbol" do
+      it "returns the description whether a symbol or string is used to look up" do
+        expect(TestResource.action_description("symbol_action")).to eql("a symbol test")
+        expect(TestResource.action_description(:symbol_action)).to eql("a symbol test")
+      end
+    end
+
+    context "when inheriting from an existing resource" do
+      class TestResourceChild < TestResource
+        action :base_action2, description: "modified base action 2 desc" do; end
+        action :base_action3 do; end
+      end
+
+      it "returns original description when a described action is not overridden in child resource" do
+        expect(TestResourceChild.action_description(:base_action1)).to eq "unmodified base action 1 desc"
+      end
+      it "returns original description when the child resource overrides an inherited action but NOT its description" do
+        expect(TestResourceChild.action_description(:base_action3)).to eq "unmodified base action 3 desc"
+      end
+      it "returns new description when the child resource overrides an inherited action and its description" do
+        expect(TestResourceChild.action_description(:base_action2)).to eq "modified base action 2 desc"
+      end
+    end
+  end
+
   describe ".default_action" do
     let(:default_action) {}
     let(:resource_class) do