Proposal: towards new API

This is a proposal, not something you can install. Opinions very welcome.

Writing M2 docs today means a separate doc ///…/// block (or a document {…} list) far away from the code, in a hypertext DSL of its own. It works, but it’s a chore, so a lot of code ends up documented badly or not at all.

While building the language server I ended up needing docs in a different shape anyway: as data, attached to the code, and in Markdown. The next pages are about what that looks like and where I think it could go:

• How LSP builds its hover: where the docs you see in the editor come from
• Inline docs and annotation: documenting code right where it’s written