Choose a documentation standard throughout the repo

[Bodacious]

Most methods outside of controller actions should have some level of documentation to describe their purpose.

The Yard syntax has been used well on some of the code, but this has not been used consistenly across the whole codebase.

TomDoc is a lightweight documentation syntax for Ruby that is used by many notable teams including GitHub. TomDoc provides the same features as yard, but is easier to write (and is more likely to be written).

TomDoc can be parsed by Yard to create the same automatically generated HTML documentation for developer reference.

We should decide on one of these documentation syntaxes (or RDoc) and enforce their use throughout the whole application.

Pros:

• Provides developers with a better explanation of the intended function of given code.
• Offers a pseudo-type-casting to add additional clarity to the contract for a given piece of code

Cons:

• Developers will have to learn whatever syntax is decided on.

[magdalenadrafiova]

@briri and @xsrust is still still relevant?

[briri]

yes. this is something we need to do still. Can certainly wait until post Rails5 though

[benjaminfaure]

We need to look into how the documentation is handled