Add @api private YARD documentation

This shows a clear warning when the documentation is viewed via rubydoc.info: "This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future." Also add comments to the same effect if people are looking at the classes directly.

Also adds a bit of Ruby Doc to public API method.

There is an [outstanding story to add more comprehensive RubyDoc](https://www.pivotaltracker.com/story/show/75691732), which will be addressed later.