Add Yard Documentation to Methods

[lcreid]

I would like to start documenting some of the methods I'm working on, simply to help me keep track of what a method is supposed to do. It seems to me the best place to put this documentation would be in the source code so it can be automatically published by Yard when we publish the gem.

This issue is to solicit feedback on the idea and to make sure I'm not going against the wishes of the community if I start documenting methods in the source.

I'm not proposing that we have to do a big push to document everything, although we could if someone wanted to. Nor am I proposing a particular technology. If there's a better alternative than Yard, let's use it.

[GBH]

This is not even about Yard docs. It's about having helpful documentation so it's possible to figure out what a given method does. Methods like these: https://github.com/bootstrap-ruby/bootstrap_form/blob/master/lib/bootstrap_form/form_builder.rb#L106 have way too much stuff going on inside so it would be helpful to document all the possible options that can be passed in and what the resulting output will be. Splitting that method apart would help quite a bit too.

You just add documentation as you touch or figure out what methods actually do.