Documentation quality checks

[zverok]

Next step in docs check: not only correction, but also quality.

Some ideas on checks:

• simple "undocumented X" for X in (class, method, constant, parameter, what else?);
• unnecessary documented return value for predicate methods (YARD does it automatically);
• wrongful documented return value type for predicate methods (when it is documented and is not boolean);
• possibly undocumented options (when last argument is options, but there is no @option tags);
• valid code syntax inside @example block and backtick-marked code blocks (highlighter which comes with YARD dependencies like markdown/rdoc would be enough: they fail to highlight on invalid syntax);
• Link::To::Class which should be {Link::To::Class} and (much harder) plaintext "Link::To::Class" too;
• common errors in docs syntax themselves (like unclosed backticks or bold/italic, lists that would not be rendered so, and so on) -- look at https://github.com/markdownlint/markdownlint
• spellchecking of docs with some existing gem?
• Example: <code> vs @example;
• Unsolved namespaces (in Rails, you can define Foo::Bar::SomeClass without defining Foo::Bar, and YARD includes it in a menu as a Foo::Bar::SomeClass, instead of Foo > Bar > SomeClass)
• ...more to come.

This issue probably will be split into several, including, alongside the checks themselves:

• some checks structure/naming conventions (see rubocop, again);
• .rubocop.yml-alike config of checks (disabling, parameters passing, style preferences);
• yard-junk:disable CheckName inline.

PS: Take a look at yardstick before doing anything!