(#18023) Document user facing classes using yardoc and show api. 

This adds yardoc to user facing classes Type, Parameter, Property,
Provider, Report, as well as classes used by these via inclusion or
delegation and where documetation was most relevant to add at the source.

This also includes puppet specific tags (@comment, and @dsl), puppet
specific templates (shows DSL for elements marked with @dsl), as well
as some general improvements to the default yard templates.

As this is the first stab at providing more comprehensive code
documentation, there are many unanswered questions in the documentation
that are marked with @todo, or ??? to indicate uncertainty.
More investigation is required to update these.

Many methods are marked as being non api. As this documentation is not final,
and only covers a portion of the puppet code base, the lack of a "private"
tag being displayed should not yet be taken as authoritiative indication
that it is api.