Work in Progress

We are still in the process of writing the documentation for Scala 3. You can help us to improve the documentation.

Are you searching for the Scala 2 documentation?

Scala 3 Migration Guide

Scaladoc settings compatibility between Scala2 and Scala3

Language

The current page is stating the status of scaladoc settings. The related Github issue can be found here for discussion

Scala2 Scala3 Description Comment Is implemented?
-doc-format _ Selects in which format documentation is rendered. Actually, old scaladoc supports only html, so it is in some way consistent with new scaladoc, which provides only html
-doc-title -project The overall name of the Scaladoc site Aliased in #11965
-doc-version -project-version   Aliased in #11965
-doc-footer -project-footer A footer on every Scaladoc page, by default the EPFL/Lightbend copyright notice. Can be overridden with a custom footer. Fixed by #11965
-doc-no-compile _ A directory containing sources which should be parsed for docstrings without compiling (e.g. AnyRef.scala) We don’t need this as we have completely different approach to that issue using -Ydocument-synthetic-types flag for synthetic types
-doc-source-url -source-links A URL pattern used to link to the source file, with some variables supported… Scala3 implementation provides richer syntax. You can find migration steps below this table.
-doc-external-doc -external-mappings Links describing locations of external dependencies’ documentations. Scala3 implementation provides richer syntax. You can find migration steps below this table.
-jdk-api-doc-base -external-mappings URL used to link Java API references. You can specify jdk via -external-mappings since they are generalized setting. You can find migration steps below this table
-doc-generator _ The fully qualified name of a doclet class, which will be used to generate the documentation. We don’t need this in Scala3
-doc-root-content -doc-root-content The file from which the root package documentation should be imported.  
-implicits _   We don’t need this in Scala3 - Contextual extension methods are always documented in Scala 3
-implicits-debug _   We don’t need this in Scala3
-implicits-show-all _   We don’t need this in Scala3
-implicits-sound-shadowing _   We don’t need this in Scala3
-implicits-hide _   We don’t need this in Scala3
-diagrams _   We don’t need this in Scala3
-diagrams-debug _   We don’t need this in Scala3
-diagrams-dot-path _   We don’t need this in Scala3
-diagrams-max-classes _   We don’t need this in Scala3
-diagrams-max-implicits _   We don’t need this in Scala3
-diagrams-dot-timeout _   We don’t need this in Scala3
-diagrams-dot-restart _   We don’t need this in Scala3
-author -author   Fixed by #11965
-raw-output _   We don’t need this in Scala3
-no-prefixes _   We don’t need this in Scala3
-skip-packages -skip-packages    
-no-link-warnings _   Not implemented yet
-expand-all-types _   Setting has been removed
-groups -groups    
-no-java-comments _   We don’t need this in Scala3
-doc-canonical-base-url -doc-canonical-base-url A base URL to use as prefix and add canonical URLs to all pages. The canonical URL may be used by search engines to choose the URL that you want people to see in search results. If unset no canonical URLs are generated. Fixed by #11965
-private -private Show all types and members. Unless specified, show only public and protected types and members. Fixed by #11965
_ -siteroot   We don’t backport it to old scaladoc N/A
_ -project-logo   Should we backport it to the old scaladoc? N/A
_ -comment-syntax   We don’t backport it to the old scaladoc N/A
_ -revision   Should we backport it to the old scaladoc? N/A
_ -social-links   Should we backport it to the old scaladoc? N/A
_ -skip-by-id   We don’t backport it to the old scaladoc N/A
_ -skip-by-regex   We don’t backport it to the old scaladoc N/A
_ -snippet-compiler-args   We don’t backport it to the old scaladoc N/A
_ -Ydocument-synthetic-types Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib  

Source links are used to point to source code at some remote repository like github or bitbucket. Hopefully, the new syntax is almost superset of the old syntax. To migrate to the new scaladoc syntax, make sure that you don’t use any of these variables: €{TPL_OWNER} or €{FILE_PATH_EXT}. Otherwise you have to rewrite your source link, using either other variables or you can use new syntax, about which you can read more at dotty docs Note that new syntax let you specify prefixes of your files paths to match specific url in case your sources are scattered in different directories or even different repositories.

External mappings

This setting is a generalized form of the old settings for javadoc/scaladoc.

Example external mapping is:

-external-mappings:.*scala.*::scaladoc3::http://dotty.epfl.ch/api/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/

A mapping is of the form ‘<regex>::[scaladoc3|scaladoc|javadoc]::<path>’. You can supply several mappings, separated by commas, as shown in the example.

Given that the old syntaxes were:

  • for scaladoc - prefix#url
  • for javadoc - just URL

one must take the regex that will match fq name (for javadoc, it can be wildcard like java.*), then concatenate it using double colons :: with one of the 3 available documentation formats, then again append :: and then provide url for where the extednal documentation is hosted.

Contributors to this page: