Remove IDE-specific ignore

Things not relevant to the project but to someone's own development set-up should
be in a global_gitignore not a per-project gitignore.
We are using YARD for documentation for this gem

So ignore the directory created when previewing the Ruby Doc.
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.