properties can have descriptions

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

3 files changed, 31 insertions, 3 deletions

diff --git a/lib/chef/mixin/properties.rb b/lib/chef/mixin/properties.rb
index 8ff2cc4501..bb08f773da 100644
--- a/lib/chef/mixin/properties.rb
+++ b/lib/chef/mixin/properties.rb
@@ -75,6 +75,7 @@ class Chef
         #     will return if the user does not set one. If this is `lazy`, it will
         #     be run in the context of the instance (and able to access other
         #     properties).
+        #   @option options [String] :description A description of the property.
         #   @option options [Boolean] :desired_state `true` if this property is
         #     part of desired state. Defaults to `true`.
         #   @option options [Boolean] :identity `true` if this property
@@ -301,6 +302,17 @@ class Chef
         raise ArgumentError, "Property #{name} is not defined in class #{self}" if !property
         property.reset(self)
       end
+
+      #
+      # The description of the property
+      #
+      # @param name [Symbol] The name of the property.
+      # @return [String] The description of the property.
+      def property_description(name)
+        property = self.class.properties[name.to_sym]
+        raise ArgumentError, "Property #{name} is not defined in class #{self}" if !property
+        property.description
+      end
     end
   end
 end
diff --git a/lib/chef/property.rb b/lib/chef/property.rb
index 9d0957dcdf..8ee9930c33 100644
--- a/lib/chef/property.rb
+++ b/lib/chef/property.rb
@@ -60,6 +60,7 @@ class Chef
     #   options).
     #   @option options [Symbol] :name The name of this property.
     #   @option options [Class] :declared_in The class this property comes from.
+    #   @option options [String] :description A description of the property.
     #   @option options [Symbol] :instance_variable_name The instance variable
     #     tied to this property. Must include a leading `@`. Defaults to `@<name>`.
     #     `nil` means the property is opaque and not tied to a specific instance
@@ -158,6 +159,15 @@ class Chef
     end
 
     #
+    # A description of this property.
+    #
+    # @return [String]
+    #
+    def description
+      options[:description]
+    end
+
+    #
     # The instance variable associated with this property.
     #
     # Defaults to `@<name>`
@@ -252,7 +262,7 @@ class Chef
     #
     def validation_options
       @validation_options ||= options.reject do |k, v|
-        [:declared_in, :name, :instance_variable_name, :desired_state, :identity, :default, :name_property, :coerce, :required, :nillable, :sensitive].include?(k)
+        [:declared_in, :name, :instance_variable_name, :desired_state, :identity, :default, :name_property, :coerce, :required, :nillable, :sensitive, :description].include?(k)
       end
     end
 
diff --git a/spec/unit/mixin/properties_spec.rb b/spec/unit/mixin/properties_spec.rb
index 1af0bc7abd..faf2d98558 100644
--- a/spec/unit/mixin/properties_spec.rb
+++ b/spec/unit/mixin/properties_spec.rb
@@ -11,6 +11,7 @@ module ChefMixinPropertiesSpec
         property :a, "a", default: "a"
         property :ab, %w{a b}, default: "a"
         property :ac, %w{a c}, default: "a"
+        property :d, "d", description: "The d property"
       end
 
       context "and a module B with properties b, ab and bc" do
@@ -30,11 +31,16 @@ module ChefMixinPropertiesSpec
           end
 
           it "A.properties has a, ab, and ac with types 'a', ['a', 'b'], and ['b', 'c']" do
-            expect(A.properties.keys).to eq [ :a, :ab, :ac ]
+            expect(A.properties.keys).to eq [ :a, :ab, :ac, :d ]
             expect(A.properties[:a].validation_options[:is]).to eq "a"
             expect(A.properties[:ab].validation_options[:is]).to eq %w{a b}
             expect(A.properties[:ac].validation_options[:is]).to eq %w{a c}
           end
+
+          it "A.properties can get the description of `d`" do
+            expect(A.properties[:d].description).to eq "The d property"
+          end
+
           it "B.properties has b, ab, and bc with types 'b', nil and ['b', 'c']" do
             expect(B.properties.keys).to eq [ :b, :ab, :bc ]
             expect(B.properties[:b].validation_options[:is]).to eq "b"
@@ -42,7 +48,7 @@ module ChefMixinPropertiesSpec
             expect(B.properties[:bc].validation_options[:is]).to eq %w{b c}
           end
           it "C.properties has a, b, c, ac and bc with merged types" do
-            expect(C.properties.keys).to eq [ :a, :ab, :ac, :b, :bc, :c ]
+            expect(C.properties.keys).to eq [ :a, :ab, :ac, :d, :b, :bc, :c ]
             expect(C.properties[:a].validation_options[:is]).to eq "a"
             expect(C.properties[:b].validation_options[:is]).to eq "b"
             expect(C.properties[:c].validation_options[:is]).to eq "c"