Generate documentation #930
Conversation
Co-Authored-By: David Binder <[email protected]>
I experimented with using Tree.Query, but we would still need to recurse into individual fields (like ops in InterfaceDefs), so we can also just recurse explicitly entirely. In the actual renderer of the documentation, we will now need to recurse using "rest" fields or specific arrays like "ops", but I think that's okay.
|
This is ready for review now. Toplevel terms and selected 2nd level terms (such as operations or constructors in data/interface) now have a We discussed my style of parsing doc comments, and I'm unsure what we've settled on. We may want to use the technique of @timsueberkrueb in #957 or the Scala 3 syntax. I think the current version looks fine though. You can generate a JSON representation of files using *we may want to change/discuss the specifics in the future. For now this includes almost all non-statement/term fields of definitions. Further work such as the frontend on which I worked in parallel will be merged in subsequent PRs (and in a different repository, most probably) Also, should I add tests for documentation generation? (and where?) |
Maybe adding a neg-Test for this would be useful (esp. since this also tests that doc-comments are at least detected in this case)? |
| InterfaceDef(IdDef(id.name, id.span) withPositionOf op, tps, List(Operation(id, Many.empty(tps.span.synthesized), vps, bps, ret) withPositionOf op)) | ||
| val doc = maybeDocumentation() | ||
| `effect` ~> operation(doc) match { | ||
| // TODO: which doc/span should be used when and where? |
effekt/shared/src/main/scala/effekt/util/DocumentationGenerator.scala
Outdated
Show resolved
Hide resolved
IDK why, but on my machine, the output of `--time=json` uses decimal
commas instead decimal points, so `"lexer": { "my/awesome/file.effekt":
14,15 }, ...`
Let's not do that. :)
We should also think about using a proper JSON library, esp. if we use
it in both documentation (#930) and here, it might just be worth to
import
[`uJson`](http://www.lihaoyi.com/post/uJsonfastflexibleandintuitiveJSONforScala.html)
or something...
Group-programmed by the Effekt team
|
Great work 👍 There's one more TODO above for spans in a desugaring in the parser. I think the only way to guarantee they are correct is to create a test case. Let me know if I can help with that! |
show-documentationandwrite-documentationfor generating JSONs of documented nodes