motoko
motoko copied to clipboard
dfinity
mo-doc generation using referenced type name vs data structure
Im having an issue where I have a public facing part of my Motoko library and an internal facing section to have some code not be exposed, while keeping all of its functionality
So in many of my files I have public type X = InternalTypes.X for many different types, exposing the ones that i want exposed. This functionally works just fine but in the generated documentation i get
## Type `X`
''' motoko no-repl
type X = InternalTypes.X
'''
Which is super unhelpful. Is it possible to have the types never show the referenced name and only show the data structure itself? Or are there any other options that you can think of? I dont want to have to duplicate all the types across all my files just to get the documentation to work
Good point! I see a similar thing in connection with imported (and non-renamed) private type names. These get suffixed in the .did file with __1 etc., and cause bloat and confusion only.
The example is
// in main.mo
private type Credit = Types.Credit;
My suggestions:
- if there is no renaming, don't generate suffixes
- if the RHS is a public type and the LHS private, keep using the public one.
Relevant source code locations:
Fixing this seems nontrivial; I encountered a similar issue when implementing type information tooltips in the VS Code extension. @ggreif @crusso, this relies on having some way to recover the original Syntax.typ from a Syntax.PathT.
Unfortunately, I think the current design of mo-doc is too simplistic to support that. It currently only has access to the syntax of Motoko code, no type information at all. To do better, we would need to replace mo-doc by a tool that is integrated with the type checker, perhaps by adding a special flag to also generate doc to moc.
