Add scaladoc docs

_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.

_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.

_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
 ---

_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:
 ---

_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 | <i class="fa fa-times fa-lg"></i> |  
+| -doc-title | -project | The overall name of the Scaladoc site | Aliased in [#11965](https://github.com/lampepfl/dotty/issues/11965) | <i class="fa fa-check fa-lg"></i> | 
+| -doc-version | -project-version | | Aliased in [#11965](https://github.com/lampepfl/dotty/issues/11965)  | <i class="fa fa-check fa-lg"></i> | 
+| -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) | <i class="fa fa-check fa-lg"></i> |  
+| -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 | <i class="fa fa-check fa-lg"></i> | 
+| -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). | <i class="fa fa-check fa-lg"></i> |
+| -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). | <i class="fa fa-check fa-lg"></i> |
+| -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) | <i class="fa fa-check fa-lg"></i> |
+| -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 |  <i class="fa fa-check fa-lg"></i> |
+| -doc-root-content | -doc-root-content | The file from which the root package documentation should be imported. | |  <i class="fa fa-check fa-lg"></i> |
+| -implicits | _ |  | We don't need this in Scala3 - Contextual extension methods are always documented in Scala 3 | <i class="fa fa-times fa-lg"></i> |
+| -implicits-debug | _ |  | We don't need this in Scala3 | <i class="fa fa-times fa-lg"></i> |
+| -implicits-show-all | _ |  | We don't need this in Scala3 |  <i class="fa fa-times fa-lg"></i> |
+| -implicits-sound-shadowing | _ | | We don't need this in Scala3 |  <i class="fa fa-times fa-lg"></i> |
+| -implicits-hide | _ |  | We don't need this in Scala3 |  <i class="fa fa-times fa-lg"></i> |
+| -diagrams | _ |  | We don't need this in Scala3 | <i class="fa fa-times fa-lg"></i> |
+| -diagrams-debug | _ |  | We don't need this in Scala3 | <i class="fa fa-times fa-lg"></i> |
+| -diagrams-dot-path | _ |  | We don't need this in Scala3 |  <i class="fa fa-times fa-lg"></i> |
+| -diagrams-max-classes | _ |  | We don't need this in Scala3 |  <i class="fa fa-times fa-lg"></i> |
+| -diagrams-max-implicits | _ |  | We don't need this in Scala3 | <i class="fa fa-times fa-lg"></i> |
+| -diagrams-dot-timeout | _ |  | We don't need this in Scala3 | <i class="fa fa-times fa-lg"></i> |
+| -diagrams-dot-restart | _ |  | We don't need this in Scala3 |  <i class="fa fa-times fa-lg"></i> |
+| -author | -author |  | Fixed by [#11965](https://github.com/lampepfl/dotty/issues/11965) | <i class="fa fa-check fa-lg"></i> | 
+| -raw-output | _ |  | We don't need this in Scala3 | <i class="fa fa-check fa-lg"></i> |
+| -no-prefixes | _ |  | We don't need this in Scala3 | <i class="fa fa-check fa-lg"></i> |
+| -skip-packages | -skip-packages |  |  | <i class="fa fa-check fa-lg"></i> |
+| -no-link-warnings | _ | | Not implemented yet | <i class="fa fa-times fa-lg"></i> |
+| -expand-all-types | _ | | Setting has been removed | <i class="fa fa-times fa-lg"></i> |
+| -groups | -groups | | | <i class="fa fa-check fa-lg"></i> | 
+| -no-java-comments | _ |  | We don't need this in Scala3 |  <i class="fa fa-check fa-lg"></i> |
+| -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) | <i class="fa fa-check fa-lg"></i> | 
+| -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) | <i class="fa fa-check fa-lg"></i> | 
+| _ | -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  |  | <i class="fa fa-check fa-lg"></i> | 
+
+## 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 '\<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. 

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..."

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
 
 ---

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