Issue #16255 has been reported by John Guthrie.
----------------------------------------
Bug #16255: conditionals seem to terminate puppetdoc processing within a class
https://projects.puppetlabs.com/issues/16255
Author: John Guthrie
Status: Unreviewed
Priority: Normal
Assignee:
Category: documentation
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.
