Adding yardoc-style inline documentation on public methods

[CSDUMMI]

Pitch

Start adding yardoc comments with in-line documentation to the Mastodon codebase consistently by:

• Encouraging PRs with yardoc in-line documentation
• Requiring all new PRs adding modules, classes or public functions to add yardoc-style comments
• Serve the HTML documentation generated by yardoc on joinmastodon.org

Motivation

In-line documentation keeps documentation and code as close to each other as possible, making it easy to update documentation along with code and identifying divergences between documented and actual behavior.

Adding in-line documentation to Mastodon, which already exists in some moduels, will make it easier to modify the mastodon codebase in the future, to fork it and to study it.

Yardoc is an established format for inline-documentation in ruby, backwards-compatible with RDoc and extendable.

Currently yardoc recognizes 21.2% of Mastodon's codebase (main@eff447a4) as being documented in some way:

Files:        1061
Modules:       147 (  144 undocumented)
Classes:      1082 (  970 undocumented)
Constants:     394 (  358 undocumented)
Attributes:    137 (    1 undocumented)
Methods:      2938 ( 2229 undocumented)
 21.20% documented

While it is infeasible to add inline documentation to all of these files, adding them for any future changes and encouraging contributions of in-line documentation as a first step into contributing to Mastodon, could make a huge difference already.