The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com

This issue tracker is now in read-only archive mode and automatic ticket export has been disabled. Redmine users will need to create a new JIRA account to file tickets using https://tickets.puppetlabs.com. See the following page for information on filing tickets with JIRA:

Bug #11384

Hash in class parameter breaks doc generation

Added by Carlos Sanchez over 4 years ago. Updated over 2 years ago.

Status:AcceptedStart date:12/14/2011
Priority:LowDue date:
Assignee:-% Done:

0%

Category:parser
Target version:-
Affected Puppet version:2.7.9 Branch:
Keywords:rdoc puppetdoc hash doc parameterized class

We've Moved!

Ticket tracking is now hosted in JIRA: https://tickets.puppetlabs.com

This ticket is now tracked at: https://tickets.puppetlabs.com/browse/PUP-1522


Description

Having a hash in a class parameter makes the Class documentation to be discarded when running puppetdoc

Running puppet doc --mode rdoc --manifestdir test/manifests/test.pp --modulepath ./

test/manifests/test.pp

# Class: test
# 
# test class. This comment is ignored by puppetdoc
class test( $p = {} ) {
}

# Class: test2
# 
# test2 class. This comment is NOT ignored by puppetdoc
class test2() {
}

I tried to narrow it down and seems an issue at manifest parse time, as the klass.doc variable is already “” in puppet/util/rdoc/parser.rb


Related issues

Related to Puppet - Bug #2364: No puppetdoc for subclass not preceded by resource or ano... Accepted 06/25/2009

History

#1 Updated by Anonymous over 4 years ago

  • Status changed from Unreviewed to Accepted

Thanks for the report. I can reproduce the problem here; thanks for being so clear about how to reproduce the problem.

#2 Updated by Jan Vansteenkiste over 3 years ago

Even better

# Class: test
# 
# test class. This comment is ignored by puppetdoc
class test {
  # This /IS/ in the docs for this class :)
  $p = {}
}

#3 Updated by Marc Tardif almost 3 years ago

A workaround for this issue is to use the hash() function from the stdlib module. To create an empty hash, simply pass an empty array: hash([])

#4 Updated by Jan Vansteenkiste almost 3 years ago

I’ve worked around this by splitting out documentation in a new file

class foobar {

  #:include: vhost.README.md
  $hash = {

  }
}

#5 Updated by Keith Edmunds over 2 years ago

We’re hitting this problem, too. It’s disappointing that a bug that is two years old and easy to reproduce has not apparently had any attention.

Most would agree that good documentation is a fundamental part of good software engineering. A broken documentation system should justify more focus than this bug appears to be receiving.

Any timescale for a fix?

Thanks, Keith

#6 Updated by Jan Vansteenkiste over 2 years ago

Redmine Issue #11384 has been migrated to JIRA:

https://tickets.puppetlabs.com/browse/PUP-1522

Also available in: Atom PDF