illuaminate
illuaminate copied to clipboard
Documentation generation improvements
While #6 has now been merged, there's a lot of things we can/should still improve:
Doc comment parsing
-
[x] Allow markdown within references: A little dubious, but might be nice to allow for
@{foo|Hello *italics*!}
. -
[x] Allow key-value pairs in tags: Namely, we should be able to handle
@param[type=number]
. -
[x] 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.
-
[x] 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
andmultishell
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
value
s 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
- [x] Warn on malformed code blocks: Basically check examples, and code blocks tagged with
lua
and verify they are valid expressions or statements.
Emitting
- [x] 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.
- Add some
- [ ] 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.