YARD docs

[tcd]

I've got a fork of Trestle with a good chunk of the existing doc comments converted to YARD complaint comments. I still need to clean them up a bit and get them reviewed, but is this something that y'all would accept a pull request for?

[spohlenz]

I'd definitely love to see an example of the the work you have done. I've experimented with YARD in the past but it's been a while. However I could definitely be swayed that this is the way to go.

I gather that the main advantage from your perspective is the automated generation of HTML docs?

[timdiggins]

Sounds great -- another big bonus of YARD docs if they have fully annotated tags (@param and @return with type information) is that it massively increases the power of any code inspection/autocompletion you have in editor / IDE (e.g. RubyMine, but works for others).

[tcd]

Sorry I let this sit a while, I've been a but swamped at work. Would y'all still be interested in this? I've got a number of doc comments added in this fork (mainly in lib/trestle/ and app/helpers/trestle/).

A few notes:

• This is incomplete, I wanted to see if there was interest before putting in more effort.
• I'm completely open to any changes, as I just kind of whipped this up in a hurry.
• I've seen options in options hash parameters documented a few different ways, what I did was based off of how AWS does their docs.
• I used Doc::Unknown as a placeholder when I was unsure of a type.
• I used Doc::HTML & Trestle::Doc::HTML as placeholders for html-building types, not exactly sure what those should be.