Issue #16255 has been updated by Henrik Lindberg. Category changed from documentation to parser Status changed from Investigating to Accepted
I started to look into this - there are two fundamental places where this could go wrong; either the lexer/parser does not recognize the comments as being documentation in the first place (there is nothing for RDoc to process), or the RDoc processor does not do what it is supposed to do. My primary suspect is that the RDoc processor is ok, it iterates the parsed result looking for AST::Resource instances and outputs their documentation (if they have any). The logic from source to associated documentation is however a long crooked meta-programming path. Here there are plenty of opportunity for things to go wrong. Comments are collected and accumulated by the lexer. The Parser calls lexer's commentpop in various places to get the accumulated comments. It does this at the beginning of statements (conditionals, etc.) It is not clear how they get assigned to doc in AST. This happens via included logic Puppet::Util::InlineDocs which is called from a set of AST classes - the method associates_doc. A lot more time is needed to actually figure out where things go wrong. Clearly it does not do this right. Marking this as accepted and that it is a parser issue (which is what I suspect). ---------------------------------------- Bug #16255: conditionals seem to terminate puppetdoc processing within a class https://projects.puppetlabs.com/issues/16255#change-74742 Author: John Guthrie Status: Accepted Priority: Normal Assignee: Henrik Lindberg Category: parser Target version: Affected Puppet version: 2.7.19 Keywords: Branch: It appears that once a conditional appears in a class, then all rdoc processing by puppet-doc terminates. For example, that the following bit of puppet code: # = Class: testing::rdocbug # # This class is for testing a potential bug in puppet-doc. This bit of # documentation should work. We are using the command "puppet doc -a -m text" class testing::rdocbug { # # == File: /tmp/workingfile # # This documentation should also be visible. file { "/tmp/workingfile": content => "foo\n"; } if $foo == 'here' { # # == File: /tmp/non-workingfile # # This documentation does not show up. file { "/tmp/non-workingfile": content => "bar\n"; } } # # == Service: non-workd # # The documentation for this service doesn't show up either, even though # we are no longer in the conditional. service { "non-workd": ensure => stopped, enable => false; } } # # = Class: testing::rdocbug2 # # Now that we are starting a new class, this documentation will show up. class testing::rdocbug2 { # # == Exec: /usr/bin/this-command-works # # This documentation will work again, since we are in a new class. exec { "/usr/bin/this-command-works": user => 'foo'; } case $baz { 'hello': { # # == File: /tmp/bye # # This bug also affect case statements. file { "/tmp/bye": content => 'bye'; } } 'bye': { # # == File: /tmp/hello # # Still in a case statement, so this doesn't show up. file { "/tmp/hello": content => 'hello'; } } } } If I run the command: puppet-doc -a -m text then I would naively expect to get: = Class: testing::rdocbug This class is for testing a potential bug in puppet-doc. This bit of documentation should work. We are using the command "puppet doc -a -m text" with appropriate manifestdir and modulepath flags. == File: /tmp/workingfile This documentation should also be visible. == File: /tmp/non-workingfile This documentation does not show up. == Service: non-workd The documentation for this service doesn't show up either, even though we are no longer in the conditional. = Class: testing::rdocbug2 Now that we are starting a new class, this documentation will show up. == Exec: /usr/bin/this-command-works This documentation will work again, since we are in a new class. == File: /tmp/bye This bug also affect case statements. == File: /tmp/hello Still in a case statement, so this doesn't show up. However, instead, I get: = Class: testing::rdocbug This class is for testing a potential bug in puppet-doc. This bit of documentation should work. We are using the command "puppet doc -a -m text" == File: /tmp/workingfile This documentation should also be visible. = Class: testing::rdocbug2 Now that we are starting a new class, this documentation will show up. == Exec: /usr/bin/this-command-works This documentation will work again, since we are in a new class. Now I understand from bug #3380 that documentation within conditionals doesn't get processed, because puppet-doc does a static analysis, and does not have the information to handle the conditionals. My first question is why couldn't we just process all rdoc documentation that is connected to a resource, whether or not that resource is in a conditional. (Perhaps I should file that as a feature?) However, there is a second part to this bug. If you look in the first class in the code example that I gave above, then you can see that there is a service resource that comes *after* the conditional, but is not contained within the conditional. However, the rdoc for that resource is not being processed either. Since that is not in a conditional, I would consider that a bug. I am seeing this with 2.7.19. and ruby 1.8.7.358 on Fedora 15. -- You have received this notification because you have either subscribed to it, or are involved in it. To change your notification preferences, please click here: http://projects.puppetlabs.com/my/account -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/puppet-bugs?hl=en.
