rdoc json compat methods

2 files changed, 12 insertions, 0 deletions

diff --git a/lib/chef/json_compat.rb b/lib/chef/json_compat.rb
index 410dd51816..80afc163e7 100644
--- a/lib/chef/json_compat.rb
+++ b/lib/chef/json_compat.rb
@@ -52,6 +52,11 @@ class Chef
       # Just call the JSON gem's parse method with a modified :max_nesting field
       def from_json(source, opts = {})
         obj = ::Yajl::Parser.parse(source)
+
+        # The old default in the json gem (which we are mimicing because we
+        # sadly rely on this misfeature) is to "create additions" i.e., convert
+        # JSON objects into ruby objects. Explicit :create_additions => false
+        # is required to turn it off.
         if opts[:create_additions].nil? || opts[:create_additions]
           map_to_rb_obj(obj)
         else
@@ -59,6 +64,8 @@ class Chef
         end
       end
 
+      # Look at an object that's a basic type (from json parse) and convert it
+      # to an instance of Chef classes if desired.
       def map_to_rb_obj(json_obj)
         res = case json_obj
         when Hash
diff --git a/lib/chef/resource.rb b/lib/chef/resource.rb
index 492b6a8f32..729632a69c 100644
--- a/lib/chef/resource.rb
+++ b/lib/chef/resource.rb
@@ -129,14 +129,19 @@ F
 
     extend Chef::Mixin::ConvertToClassName
 
+    # Track all subclasses of Resource. This is used so names can be looked up
+    # when attempting to deserialize from JSON. (See: json_compat)
     def self.resource_classes
       @resource_classes ||= []
     end
 
+    # Callback when subclass is defined. Adds subclass to list of subclasses.
     def self.inherited(subclass)
       resource_classes << subclass
     end
 
+    # Look up a subclass by +class_name+ which should be a string that matches
+    # `Subclass.name`
     def self.find_subclass_by_name(class_name)
       resource_classes.first {|c| c.name == class_name }
     end