Fix 2841 - Puppetdoc/RDoc parses realize function

Puppetdoc wasn't parsing the realize function.
This patch let puppetdoc find realize and display in RDoc html
mode the list of realized resource per class or node.

Signed-off-by: Brice Figureau <brice-puppet@daysofwonder.com>

4 files changed, 66 insertions, 18 deletions

diff --git a/lib/puppet/util/rdoc/code_objects.rb b/lib/puppet/util/rdoc/code_objects.rb
index be5e468c0..995869987 100644
--- a/lib/puppet/util/rdoc/code_objects.rb
+++ b/lib/puppet/util/rdoc/code_objects.rb
@@ -88,12 +88,13 @@ module RDoc
     # It is mapped to a HTMLPuppetClass for display
     # It leverages RDoc (ruby) Class
     class PuppetClass < ClassModule
-        attr_accessor :resource_list, :requires, :childs
+        attr_accessor :resource_list, :requires, :childs, :realizes
 
         def initialize(name, superclass)
             super(name,superclass)
             @resource_list = []
             @requires = []
+            @realizes = []
             @childs = []
         end
 
@@ -116,6 +117,10 @@ module RDoc
             add_to(@requires, required)
         end
 
+        def add_realize(realized)
+            add_to(@realizes, realized)
+        end
+
         def add_child(child)
             @childs << child
         end
diff --git a/lib/puppet/util/rdoc/generators/puppet_generator.rb b/lib/puppet/util/rdoc/generators/puppet_generator.rb
index f06879fff..1a4219ff4 100644
--- a/lib/puppet/util/rdoc/generators/puppet_generator.rb
+++ b/lib/puppet/util/rdoc/generators/puppet_generator.rb
@@ -334,8 +334,8 @@ module Generators
         def build_referenced_list(list)
             res = []
             list.each do |i|
-                ref = @context.find_symbol(i.name)
-                ref = ref.viewer if ref
+                ref = AllReferences[i.name] || @context.find_symbol(i.name)
+                ref = ref.viewer if ref and ref.respond_to?(:viewer)
                 name = i.respond_to?(:full_name) ? i.full_name : i.name
                 h_name = CGI.escapeHTML(name)
                 if ref and ref.document_self
@@ -409,6 +409,9 @@ module Generators
             rl = build_require_list(@context)
             @values["requires"] = rl unless rl.empty?
 
+            rl = build_realize_list(@context)
+            @values["realizes"] = rl unless rl.empty?
+
             cl = build_child_list(@context)
             @values["childs"] = cl unless cl.empty?
 
@@ -419,6 +422,10 @@ module Generators
             build_referenced_list(context.requires)
         end
 
+        def build_realize_list(context)
+            build_referenced_list(context.realizes)
+        end
+
         def build_child_list(context)
             build_referenced_list(context.childs)
         end
@@ -499,6 +506,9 @@ module Generators
             rl = build_require_list(@context)
             @values["requires"] = rl unless rl.empty?
 
+            rl = build_realize_list(@context)
+            @values["realizes"] = rl unless rl.empty?
+
             cl = build_child_list(@context)
             @values["childs"] = cl unless cl.empty?
 
@@ -608,6 +618,10 @@ module Generators
             build_referenced_list(context.requires)
         end
 
+        def build_realize_list(context)
+            build_referenced_list(context.realizes)
+        end
+
         def build_child_list(context)
             build_referenced_list(context.childs)
         end
diff --git a/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb b/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb
index bae9fc723..e03381f22 100644
--- a/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb
+++ b/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb
@@ -615,6 +615,19 @@ END:requires
     </div>
 ENDIF:requires
 
+    <!-- if realizes -->
+IF:realizes
+    <div id="realizes">
+      <h3 class="section-bar">Realized Resources</h3>
+
+      <div id="realizes-list">
+START:realizes
+        <span class="realizes-name">HREF:aref:name:</span>
+END:realizes
+      </div>
+    </div>
+ENDIF:realizes
+
 START:sections
     <div id="section">
 IF:sectitle
@@ -626,7 +639,6 @@ IF:seccomment
 ENDIF:seccomment
 ENDIF:sectitle
 
-
 <!-- if facts -->
 IF:facts
     <div id="class-list">
diff --git a/lib/puppet/util/rdoc/parser.rb b/lib/puppet/util/rdoc/parser.rb
index 416711d59..c2d307751 100644
--- a/lib/puppet/util/rdoc/parser.rb
+++ b/lib/puppet/util/rdoc/parser.rb
@@ -161,6 +161,22 @@ class Parser
         end
     end
 
+    # create documentation for realize statements we can find in +code+
+    # and associate it with +container+
+    def scan_for_realize(container, code)
+        code = [code] unless code.is_a?(Array)
+        code.each do |stmt|
+            scan_for_realize(container,stmt.children) if stmt.is_a?(Puppet::Parser::AST::ASTArray)
+
+            if stmt.is_a?(Puppet::Parser::AST::Function) and stmt.name == 'realize'
+                stmt.arguments.each do |realized|
+                    Puppet.debug "found #{stmt.name}: #{realized}"
+                    container.add_realize(Include.new(realized.to_s, stmt.doc))
+                end
+            end
+        end
+    end
+
     # create documentation for global variables assignements we can find in +code+
     # and associate it with +container+
     def scan_for_vardef(container, code)
@@ -184,20 +200,9 @@ class Parser
 
             if stmt.is_a?(Puppet::Parser::AST::Resource) and !stmt.type.nil?
                 begin
-                    type = stmt.type.split("::").collect { |s| s.capitalize }.join("::")
-                    title = stmt.title.is_a?(Puppet::Parser::AST::ASTArray) ? stmt.title.to_s.gsub(/\[(.*)\]/,'\1') : stmt.title.to_s
-                    Puppet.debug "rdoc: found resource: %s[%s]" % [type,title]
-
-                    param = []
-                    stmt.params.children.each do |p|
-                        res = {}
-                        res["name"] = p.param
-                        res["value"] = "#{p.value.to_s}" unless p.value.nil?
-
-                        param << res
-                    end
-
-                    container.add_resource(PuppetResource.new(type, title, stmt.doc, param))
+                    ref = resource_stmt_to_ref(stmt)
+                    Puppet.debug "rdoc: found resource: %s[%s]" % [ref.type, ref.title]
+                    container.add_resource(ref)
                 rescue => detail
                     raise Puppet::ParseError, "impossible to parse resource in #{stmt.file} at line #{stmt.line}: #{detail}"
                 end
@@ -205,6 +210,16 @@ class Parser
         end
     end
 
+    def resource_stmt_to_ref(stmt)
+        type = stmt.type.split("::").collect { |s| s.capitalize }.join("::")
+        title = stmt.title.is_a?(Puppet::Parser::AST::ASTArray) ? stmt.title.to_s.gsub(/\[(.*)\]/,'\1') : stmt.title.to_s
+
+        param = stmt.params.children.collect do |p|
+            {"name" => p.param, "value" => p.value.to_s}
+        end
+        PuppetResource.new(type, title, stmt.doc, param)
+    end
+
     # create documentation for a class named +name+
     def document_class(name, klass, container)
         Puppet.debug "rdoc: found new class %s" % name
@@ -228,6 +243,7 @@ class Parser
         code ||= klass.code
         unless code.nil?
             scan_for_include_or_require(cls, code)
+            scan_for_realize(cls, code)
             scan_for_resource(cls, code) if Puppet.settings[:document_all]
         end
 
@@ -251,6 +267,7 @@ class Parser
         code ||= node.code
         unless code.nil?
             scan_for_include_or_require(n, code)
+            scan_for_realize(n, code)
             scan_for_vardef(n, code)
             scan_for_resource(n, code) if Puppet.settings[:document_all]
         end