The new Scala version 3 comes with a completely new implementation of the documentation generator Scaladoc, rewritten from scratch. In this article you can find highlights of new features that are or will be introduced to Scaladoc. For general reference, visit Scaladoc manual.
The biggest change introduced in the new version of Scaladoc is the change of the default language for docstrings. So far Scaladoc only supported Wikidoc syntax.
The new Scaladoc can still parse legacy
Wikidoc syntax, however Markdown has been chosen as a primary language for formatting comments.
To switch back to
Wikidoc one can pass a global flag before running the
doc task or one can define it for specific comments via the
@syntax wiki directive.
For more information on how to use the full power of docstings, check out Scaladoc docstrings
Scaladoc also provides an easy way for creating static sites for both documentation and blog posts in the similar way as Jekyll does. Thanks to this feature, you can store your documentation along-side with the generated Scaladoc API in a very convenient way.
For more information on how to configure the generation of static sites check out Static documentation chapter
Blog posts are a specific type of static sites. In the Scaladoc manual you can find additional information about how to work with blog posts.
Furthermore, Scaladoc provides an easy way to configure your social media links e.g. Twitter or Discord.
The following features are currently (May 2021) not stable to be released with scaladoc, however we are happy to hear your feedback. Each feature has its own thread at scala-lang contributors site, where you can share your opinions.
One of the experimental features of Scaladoc is a compiler for snippets. This tool will allow you to compile snippets that you attach to your docstring
to check that they actually behave as intended, e.g., to properly compile. This feature is very similar to the
but will be shipped with Scaladoc out of the box for easy setup and integration into your project. Making snippets interactive—e.g., letting users edit and compile them in the browser—is under consideration, though this feature is not in scope at this time.
- Hiding code
- Assert compilation errors
- Snippet includes
Searching for functions by their symbolic names can be time-consuming. That is why the new scaladoc allows you to search for methods and fields by their types.
So, for a declaration:
extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ...
Instead of searching for
span we can also search for
IArray[A] => (A => Boolean) => (IArray[A], IArray[A]).
To use this feature simply type the signature of the function you are looking for in the scaladoc searchbar. This is how it works:
For more information see Guides
Note that this feature is still in development, so it can be subject to considerable change. If you encounter a bug or have an idea for improvement, don’t hesitate to create an issue on Inkuire or dotty.