(#22180) Provide doc --mode rdoc parsing under Ruby 1.9

Puppet's RDoc parser was only compatible with RDoc 1, which is part of
Ruby 1.8.  RDoc's internals and API change between version 1 and 2+.

This commit refactors the rdoc/parser into an
rdoc/parser/puppet_parser_core.rb module which is included by two
different rdoc1 and rdoc2 parser classes.

It allows generation in either Ruby 1.8 or Ruby 1.9, but the HTML
renderer under Ruby 1.9 is stll the default, hence the format is not
optimal, and some elements, notable plugins and nodes, are not present.
(#22180) Make function, type, fact and node appear in rdoc2 output

The driver for Rdoc1 uses CodeObject classes with specialized
data structures for function, type ("plugins"), facts and nodes. The
standard generators for RDoc2 does not know about these and thus
no output was generated.

This commit changes this for RDoc2 by adding the missing parts using
standard Ruby CodeObject elements (module, method, etc.)

Note that the puppet specific parser is very picky in what it considers
to be a function, type, fact, etc. In fact, it was so picky that it
would almost never find certain elements. This commit also relaxes the
parsing to allow all functions that have :arity specified to be found.

The order in which the parsed object are intitialized is changed (all
details set before adding it to the container). This since the RDoc2
variant creates a different object based on the given data
(documentation is driven from this copy, not the original).
(#22180) Add integration test for puppet doc --mode rdoc

We were lacking any comprehensive testing of the interaction between
puppet doc and rdoc.  This integration test checks either the rdoc1 or
rdoc2 output (depending on which version of rdoc is present on the
system) for all of the basic module constructs we are documenting:
modules, classes, defined types, nodes, and plugin facts, types and
functions.  It tests both site manifests and modules.
(#22180) Fix broken rdoc1 features

There were a number of rdoc1 features (tracking of included, required
modules, realized virtual resources, all resources when :document_all
setting is true, and global variables) which had not been functioning
due to the parser wrapping statements in
Puppet::Parser::AST::BlockExpression instances now rather than
Puppet::Parser::AST::Array instances.

This is now fixed so that these areas are documented when using rdoc1.
Only included classes is documented in rdoc2, however.  Documenting the
remaining elements would require writing a new renderer.
(#22180) Recapture class comments under Ruby 2.0 RDoc

RDoc 2+ has an RDoc::ClassModule.add_comment(comment,location) method
which is the preferred method of setting comments for a class.  RDoc
shipping with Ruby 1.9 seems to fall back to using the @comment, which
is how rdoc1 handled this, but Ruby 2.0's rdoc seems to be stricter and
requires use of add_comment.

This patch overrides the add_comment method in our PuppetModule,
PuppetClass, PuppetNode code objects with a version compatible with
either rdoc1 or 2.  It also tests for module level README comments being
incorporated.
Merge pull request #2009 from jpartlow/issue/master/22180-fix-rdoc-parsing-on-ruby-1.9

Issue/master/22180 fix rdoc parsing on ruby 1.9