(#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.