diff --git a/_overviews/scala3-migration/options-intro.md b/_overviews/scala3-migration/options-intro.md index ad6b2dc29b..5dd85a3e16 100644 --- a/_overviews/scala3-migration/options-intro.md +++ b/_overviews/scala3-migration/options-intro.md @@ -17,3 +17,5 @@ To do so you can refer to the [Lookup Table](options-lookup.html). > It just prints a warning and ignores the option. You can also discover the new Scala 3 compiler options, that have no equivalent in Scala 2.13, in the [New Compiler Options](options-new.html) page. + +For scaladoc settings reference and their compatibility with Scala2 scaladoc, read [Scaladoc settings compatibility between Scala2 and Scala3](scaladoc-settings-compatibility.html) page. diff --git a/_overviews/scala3-migration/options-new.md b/_overviews/scala3-migration/options-new.md index 980f4c2712..63ee5e15ff 100644 --- a/_overviews/scala3-migration/options-new.md +++ b/_overviews/scala3-migration/options-new.md @@ -4,7 +4,7 @@ type: section description: This chapter lists all the new compiler options in Scala 3 num: 23 previous-page: options-lookup -next-page: plugin-intro +next-page: scaladoc-settings-compatibility --- The current page only contains the options that were added in Scala 3.0.x. diff --git a/_overviews/scala3-migration/plugin-intro.md b/_overviews/scala3-migration/plugin-intro.md index 8662c8da93..ea172d69cc 100644 --- a/_overviews/scala3-migration/plugin-intro.md +++ b/_overviews/scala3-migration/plugin-intro.md @@ -2,7 +2,7 @@ title: Compiler Plugins type: chapter description: This section shows how to migrate from using Scala 2 compiler plugins -num: 24 +num: 25 previous-page: options-new next-page: plugin-kind-projector --- diff --git a/_overviews/scala3-migration/plugin-kind-projector.md b/_overviews/scala3-migration/plugin-kind-projector.md index c60b33b7b0..28493a8d01 100644 --- a/_overviews/scala3-migration/plugin-kind-projector.md +++ b/_overviews/scala3-migration/plugin-kind-projector.md @@ -2,7 +2,7 @@ title: Kind Projector Migration type: section description: This section shows how to migrate from the kind-projector plugin to Scala 3 kind-projector syntax -num: 25 +num: 26 previous-page: plugin-intro next-page: --- diff --git a/_overviews/scala3-migration/scaladoc-settings-compatibility.md b/_overviews/scala3-migration/scaladoc-settings-compatibility.md new file mode 100644 index 0000000000..4f111eb51a --- /dev/null +++ b/_overviews/scala3-migration/scaladoc-settings-compatibility.md @@ -0,0 +1,84 @@ +--- +title: Scaladoc settings compatibility between Scala2 and Scala3 +type: section +description: This chapter lists all the scaladoc options for Scala 2 and Scala 3, and explains the relations between them. +num: 24 +previous-page: options-new +next-page: plugin-intro +--- + +The current page is stating the status of scaladoc settings. The related Github issue can be found here for [discussion](https://github.com/lampepfl/dotty/issues/11907) + + +| 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](https://github.com/lampepfl/dotty/issues/11965) | | +| -doc-version | -project-version | | Aliased in [#11965](https://github.com/lampepfl/dotty/issues/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](https://github.com/lampepfl/dotty/issues/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](#source-links). | | +| -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](#external-mappings). | | +| -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](#external-mappings) | | +| -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](https://github.com/lampepfl/dotty/issues/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](https://github.com/lampepfl/dotty/issues/11965) | | +| -private | -private | Show all types and members. Unless specified, show only public and protected types and members. | Fixed by [#11965](https://github.com/lampepfl/dotty/issues/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 + +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](https://dotty.epfl.ch/docs/usage/scaladoc/settings.html) +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 '\::\[scaladoc3|scaladoc|javadoc]::\'. 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. diff --git a/index.md b/index.md index 0aa20d401f..3764d39dea 100644 --- a/index.md +++ b/index.md @@ -40,6 +40,10 @@ scala3-sections: description: "The Scala 3 language reference." icon: "fa fa-book" link: https://dotty.epfl.ch/docs/reference/overview.html + - title: "All new Scaladoc for Scala 3" + description: "Highlights of new features for Scaladoc" + icon: "fa fa-star" + link: /scala3/scaladoc.html scala2-sections: - title: "First Steps..." diff --git a/resources/images/scala3/scaladoc/blog-post.png b/resources/images/scala3/scaladoc/blog-post.png new file mode 100644 index 0000000000..f8db0483d2 Binary files /dev/null and b/resources/images/scala3/scaladoc/blog-post.png differ diff --git a/resources/images/scala3/scaladoc/inkuire.gif b/resources/images/scala3/scaladoc/inkuire.gif new file mode 100644 index 0000000000..3cd999b375 Binary files /dev/null and b/resources/images/scala3/scaladoc/inkuire.gif differ diff --git a/resources/images/scala3/scaladoc/snippet-compiler1.gif b/resources/images/scala3/scaladoc/snippet-compiler1.gif new file mode 100644 index 0000000000..d3573e395f Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler1.gif differ diff --git a/resources/images/scala3/scaladoc/snippet-compiler2.gif b/resources/images/scala3/scaladoc/snippet-compiler2.gif new file mode 100644 index 0000000000..2074c74ebb Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler2.gif differ diff --git a/resources/images/scala3/scaladoc/social-links.png b/resources/images/scala3/scaladoc/social-links.png new file mode 100644 index 0000000000..4c20568c7c Binary files /dev/null and b/resources/images/scala3/scaladoc/social-links.png differ diff --git a/resources/images/scala3/scaladoc/static-site.png b/resources/images/scala3/scaladoc/static-site.png new file mode 100644 index 0000000000..9f27f058b2 Binary files /dev/null and b/resources/images/scala3/scaladoc/static-site.png differ diff --git a/scala3/index.md b/scala3/index.md index 49e7397f71..0d57bc78fb 100644 --- a/scala3/index.md +++ b/scala3/index.md @@ -40,5 +40,9 @@ sections: description: "The Scala 3 language reference." icon: "fa fa-book" link: https://dotty.epfl.ch/docs/reference/overview.html + - title: "All new Scaladoc for Scala 3" + description: "Highlights of new features for Scaladoc" + icon: "fa fa-star" + link: /scala3/scaladoc.html --- diff --git a/scala3/scaladoc.md b/scala3/scaladoc.md new file mode 100644 index 0000000000..75a02292c1 --- /dev/null +++ b/scala3/scaladoc.md @@ -0,0 +1,71 @@ +--- +layout: singlepage-overview +title: New features for Scaladoc +--- + +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](https://dotty.epfl.ch/docs/usage/scaladoc/) + +## New features + +### Markdown syntax + +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-docstrings] + + +### Static site + +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][static-documentation] chapter + +![](../resources/images/scala3/scaladoc/static-site.png) + +### Blog posts + +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][built-in-blog]. + +![](../resources/images/scala3/scaladoc/blog-post.png) + +### Social links + +Furthermore, Scaladoc provides an easy way to configure your [social media links][social-links] e.g. Twitter or Gitter. + +![](../resources/images/scala3/scaladoc/social-links.png){: style="width: 180px"} + +## Experimental features + +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. + +### Snippets compiler + +One of the experimental features of Scaladoc will be a snippets compiler. This tool will allow you to compile snippets that you attach to your docstring +to check that they actually behave as intended, e. g. compile or throw some exception. The feature is very similar to `tut` or `mdoc` tools, +but will be shipped with Scaladoc out of the box for easy setup and integration into your project. Making snippets interactive, e. g. user could edit them and compile in the browser is under consideration, though it is not in scope yet. + +For more information you can follow this [thread](https://contributors.scala-lang.org/t/snippet-validation-in-scaladoc-for-scala-3/4976) + +![](../resources/images/scala3/scaladoc/snippet-compiler2.gif) +![](../resources/images/scala3/scaladoc/snippet-compiler1.gif) + +### Type-signature browsing + +Haskell programmers are probably familiar with Hoogle - a documentation search engine that allows you browse the docs by signatures rather than symbolic names. Since many Scala developers are also functional programming fans, we decided to add a similar functionality to Scaladoc. The whole tool is based on [Inkuire](https://github.com/VirtusLab/Inkuire), which works with Kotlin and is being currently adapted to Scala 3. + +![](../resources/images/scala3/scaladoc/inkuire.gif) + +To be up-to-date with this feature you can follow this [thread](https://contributors.scala-lang.org/t/pre-sip-scaladoc-search-by-type-signature/1604/15). +Note that this feature is in an early stage of development. We still don't support type lambdas, higher-kinded types, and some other Scala features. + + + +[scaladoc-docstrings]: https://dotty.epfl.ch/docs/usage/scaladoc/scaladocDocstrings.html +[static-documentation]: https://dotty.epfl.ch/docs/usage/scaladoc/staticSite.html +[built-in-blog]: https://dotty.epfl.ch/docs/usage/scaladoc/blog.html +[social-links]: https://dotty.epfl.ch/docs/usage/scaladoc/settings.html#-social-links