Documentation generation improvements

[SquidDev]

While #6 has now been merged, there's a lot of things we can/should still improve:

Doc comment parsing

• Allow markdown within references: A little dubious, but might be nice to allow for @{foo|Hello *italics*!}.

• Allow key-value pairs in tags: Namely, we should be able to handle @param[type=number].

• Better position tracking: Ideally unresolved references, malformed tags, etc... would boil down to their actual position, rather than just a generic "this is the correct comment".

• Fix whitespace handling: Currently, the following don't do what one might hope:

  --- @param foo Some comment which runs on multiple lines.
  --             But this is formatted as a code block, rather than
  --             a paragraph.

  I think a good rule would be "if all lines are indented at least up to the description's start, then strip up to there".

  On a related note, we also are too aggressive in removing/stripping whitespace. We really should only be removing a single leading space on basic descriptions.

Comment processing

• Sections: We should be able to insert standalone doc comments with a @section tag, which declare a new section (with the title of this section being the first line/summary).

  However, it's really not clear how this should work given our more data-flow based approach to generation. This is something we need to think about a lot more first.

• Manually exporting something: It might be nice to say "this thing is exported" when our generator cannot work it out. I guess I'm mostly thinking the shell and multishell libraries in CC:T, which inject globals in a bit of a weird way.

• Stricter union checks: We really need to verify arguments match up. My rewrite branch had a nice feature where if the doc comment and body were next to each other (the common case), then we'd check the two together, rather than building two values and combining them.

• Better handling of constants: We should probably require a @const tag for constant values, rather than trying to guess it.

• Type hints on arbitrary variables: I'm thinking something like @is or @of annotation.

• @include or some other inheritance system: I really want a system to inherit doc comments from another module or type (such as for term redirects in CC:T). However, it is really not clear how to do so without creating lots of dependency cycles within the documentation system.

Linters

• Warn on malformed code blocks: Basically check examples, and code blocks tagged with lua and verify they are valid expressions or statements.

Emitting

• Allow linking to source code, either on GitHub or elsewhere.
  • Add some source-url configuration option. I'm thinking this should accept a string with some template parameters (say, https://my.fancy.website/${path}#l${line}).
  • Some way to access VCS info (and then substitute it into the template). Probably can just run git rev-parse HEAD for now.
• Better templating: I'm not sure how much we need right now, but it'd be really nice to have some ability to modify the emitted HTML without having to write your own OCaml documentation emitter.