Talkin' 'bout my documentation

[SquidDev]

This is my documentation, this is my documentation baby. Or rather it isn't, as we have no way to generate documentation from Amulet source code.

I think we can go the same route that OCaml does - (** Foo *) marks a documentation comment. We attempt to find which node this belongs to, and if we cannot find one, issue a warning.

We already have a mechanism for lexing out trivial nodes. I don't think we can deal with these in the parser,

Nodes to document

We need documentation for the following:

• Modules
• Classes and class methods
• Bindings (both top-level let and foreign). It might be worth allowing documentation on non-top-level lets as well.
• Types and constructors

Ideally we would also be able to document individual fields of records, and possibly function arguments, but this may be a little harder to manage.

Syntax of doc comments

I think it's possibly worth going the same route as we did for Urn, and just allowing markdown as the "primary" syntax for doc comments. That said, we need some syntax for linking to other declared variables.

I'm somewhat tempted to abuse Markdown link notation, and have [foo][] link to some variable "foo" (allowing [See `foo`][foo]). Probably worth going down the OCaml route again, and allowing type:foo, class:foo, etc... in order to disambiguate.