The docs has to be generated statically (outside of runtime) but some documentation elements might need to be dynamic. We should explore how macros/inline defs/typelevel programming can be used to generate such information at compile time.
Example use cases:
- reusing a string in mutliple places
- referencing another symbol from a doc
- building "tags" map to attach arbitratyr metatdat to symbols
Possible approaches
- Macros - probably the most powerful but we shouldn't force users to write custom macros for most common use cases. It could be a fallback but we should provide pre-made macros for what we expect to be important
- Inline def - we need to know what can be inlined and how complicated that is?
- type-level compuatations - value-level objects might or might not be available at compile time, depending if the compiler was able to fully resolve them into literals. OTOH type-level objects are alvways available at compile time by definition. We could possibly leverage it to build a safer API. That being said, we not necessairly need a very safe API, as the docs generation will run alongside the compilation hence it can be seen as equivalent to compilation.
The docs has to be generated statically (outside of runtime) but some documentation elements might need to be dynamic. We should explore how macros/inline defs/typelevel programming can be used to generate such information at compile time.
Example use cases:
Possible approaches