RFC: Use YARD to document API

[slonopotamus]

Motivation:

1. While rubydoc.org understands some of the current documentation format, there are other tools that do not. Most notable example is RubyMine. I haven't checked VSCode, to be honest.
2. Tools (including rubydoc.org) cannot infer nullability from current documentation (should I say "nillability" in Ruby?).
3. Tools (including rubydoc.org) do not properly understand variant types.
4. Things like visibility are already described by code itself and feel redundant.

[mojavelinux]

I came to similar conclusions when working on Asciidoctor core...though I've yet to fully apply the change there.

[slonopotamus]

I don't think converting the whole codebase in one go is manageable, because at least nullability requires conscious thoughts. In total, I spent ~20mins on AbstractBlock in current PR and not fully sure I got everything right. So, my suggestion is to do it gradually.

[ggrossetie]

Speaking of YARD it would be great if we could publish the API documentation on https://docs.asciidoctor.org/ (HTML pages) instead of relying on https://www.rubydoc.info/

@slonopotamus If you are interested it might be a good idea to set it up on the Asciidoctor EPUB3 project first?

[slonopotamus]

Sure, we can use other project for testing.

Though, I want to add a couple of thoughts:

1. I'm not sure publishing API on a website has much value. We use API when writing code, so we're in IDE, which we use to navigare through code. And why argument/return types are important is because they allow IDE to offer autocomplete and provide warnings when wrong types are used.
2. Asciidoctor Core is much more important API-wise because it is used by extensions. I haven't heard about anyone writing code that would extend Asciidoctor EPUB3. Type info can be useful within a program, but my main interest is about externally-visible stuff.

[mojavelinux]

Please discuss hosting the API in asciidoctor/asciidoctor.org#1011 (or in the dev stream in the project chat).