Add rake doc task to generate documentation from inline comments

[jeffmccune]

Working with the types and providers, there is little documentation for the class and instance methods. This isn't a huge problem, much of it is self-explanatory, however it would make maintenance of the module much more accessible to have YARD documentation for the types and providers.

As an example, I tend to reach for this cheatsheet when adding code comments.

[jeffmccune]

For types and providers, this is less useful than I hoped. Puppet::Type.newtype() obscures any inline documentation from YARD because it's nested in a passed block.

[ghoneycutt]

What about https://github.com/puppetlabs/puppet-strings ?

[jeffmccune]

What about https://github.com/puppetlabs/puppet-strings ?

Great idea! Exactly what I was looking for.

[jeffmccune]

puppet-strings is great, and I'm going to put up a PR adding the rake tasks to generate documentation.

The only gotcha is that helper methods inside of a type or provider block are still not parsed. I believe this is a result of the meta-programming involved in Puppet::Type.newtype(:sensu_check) { ... }.

To handle my original need to document a helper method, the method should be placed into a pure Ruby class and included inside the closure passed to Puppet::Type.newtype. This will allow Yard (via puppet strings) to parse the PuppetX namespace like it normally does now.

I'll add a second issue to record the need to update all of the inline documentation comments to YARD syntax. This will be pretty straight forward and mechanical with some vim macros, but it needs to happen after #682 and related changes are merged into master.