allow resources to be documented

Signed-off-by: Thom May <thom@chef.io>

2 files changed, 54 insertions, 2 deletions

diff --git a/lib/chef/resource.rb b/lib/chef/resource.rb
index ac1146a647..0351f6231e 100644
--- a/lib/chef/resource.rb
+++ b/lib/chef/resource.rb
@@ -1174,8 +1174,8 @@ class Chef
     # Internal Resource Interface (for Chef)
     #
 
-    FORBIDDEN_IVARS = [:@run_context, :@not_if, :@only_if, :@enclosing_provider]
-    HIDDEN_IVARS = [:@allowed_actions, :@resource_name, :@source_line, :@run_context, :@name, :@not_if, :@only_if, :@elapsed_time, :@enclosing_provider]
+    FORBIDDEN_IVARS = [:@run_context, :@not_if, :@only_if, :@enclosing_provider, :@description, :@introduced, :@examples]
+    HIDDEN_IVARS = [:@allowed_actions, :@resource_name, :@source_line, :@run_context, :@name, :@not_if, :@only_if, :@elapsed_time, :@enclosing_provider, :@description, :@introduced, :@examples]
 
     include Chef::Mixin::ConvertToClassName
     extend Chef::Mixin::ConvertToClassName
@@ -1374,6 +1374,27 @@ class Chef
       end
     end
 
+    def self.description(description = "NOT_PASSED")
+      if description != "NOT_PASSED"
+        @description = description
+      end
+      @description
+    end
+
+    def self.introduced(introduced = "NOT_PASSED")
+      if introduced != "NOT_PASSED"
+        @introduced = introduced
+      end
+      @introduced
+    end
+
+    def self.examples(examples = "NOT_PASSED")
+      if examples != "NOT_PASSED"
+        @examples = examples
+      end
+      @examples
+    end
+
     #
     # The cookbook in which this Resource was defined (if any).
     #
diff --git a/spec/unit/resource_spec.rb b/spec/unit/resource_spec.rb
index 934a613eee..fe853922a1 100644
--- a/spec/unit/resource_spec.rb
+++ b/spec/unit/resource_spec.rb
@@ -387,6 +387,37 @@ describe Chef::Resource do
     end
   end
 
+  context "Documentation of resources" do
+    it "can have a description" do
+      c = Class.new(Chef::Resource) do
+        description "my description"
+      end
+      expect(c.description).to eq "my description"
+    end
+
+    it "can say when it was introduced" do
+      c = Class.new(Chef::Resource) do
+        introduced "14.0"
+      end
+      expect(c.introduced).to eq "14.0"
+    end
+
+    it "can have some examples" do
+      c = Class.new(Chef::Resource) do
+        examples <<-EOH
+resource "foo" do
+  foo foo
+end
+        EOH
+      end
+      expect(c.examples).to eq <<-EOH
+resource "foo" do
+  foo foo
+end
+        EOH
+    end
+  end
+
   describe "self.resource_name" do
     context "When resource_name is not set" do
       it "and there are no provides lines, resource_name is nil" do