Scala3doc: Unified documentation #9
romanowski
started this conversation in
Ideas
Replies: 1 comment
-
Scala 3 documentation uses a raw form of that feature to merge various compilation units to be combined into Scala 3 docs. The configuration is here. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
From a blogpost:
Scala compiler (and by extension scaladoc) operates on the level of compilation units: a set of source files compiled together to single output using a single classpath as well as a set of compiler options. Sometimes libraries are split into many compilation units even though users should consume it as a single compilation unit. Why is that? Performance, macros definitions, and project history are among the many reasons libraries are split into multiple compilations units. As you probably have guessed, Scaladoc will generate multiple documentation instances in such case, making documentation inconvenient and misleading.
Akka was the first project in the Scala community that implemented merging APIs, and Eugene Yokota transformed it later into sbt-unidoc. Sbt-unidoc can combine Scala and Java documentation from across many sbt projects.
Scala3doc is a standalone tool that consumes .tasty files — fully typed ASTs serialized into binary format. This approach gives us more control in terms of what we will document simply by providing extra tasty files or excluding parts of compiler output. Yes, at this very moment, Scala3doc can generate single documentation for multiple projects by merely adding all generated .tasty files and inputs and properly configuring classpath (
doc/sources
anddoc/libraryClasspath
settings in sbt).In future, we plan to provide a set of settings and tasks to make configuration and future maintenance as straightforward as possible.
In Scala 3 .tasty files are present by default in published jars, leading us to another possible feature. We can use that information to generate a single aggregated documentation for all dependencies in the project. Having a single, aggregated documentation that is always up to date may be really helpful, especially when dealing with monorepos or bigger applications.
Beta Was this translation helpful? Give feedback.
All reactions