Scala3doc: add documentation for API links

Author: abgruszecki

docs/docs/usage/scala3doc/docComments.md

@@ -4,16 +4,42 @@ title: API Documentation
 
 # {{ page.title }}
 
-Scala3doc main feature is to create API documentation based on [doc comments](https://docs.scala-lang.org/style/scaladoc.html) known from scaladoc as well well as new syntax introduced in Scala 3.
+Scala3doc's main feature is creating API documentation from code comments.
 
-## New syntax
+By default, the code comments are understood as Markdown, though we also support
+Scaladoc's old [Wiki syntax](https://docs.scala-lang.org/style/scaladoc.html).
 
-### Links
+## Syntax
 
-The goal with the link syntax was to be as Scaladoc-compatible as possible,
-while also making the links a bit more pleasant to type and read.
-For the time being, Scala3doc mostly keeps Scaladoc's definition link syntax. We
-did, however, implement some improvements to it:
+### Definition links
+
+Our definition link syntax is quite close to Scaladoc's syntax, though we have made some
+quality-of-life improvements.
+
+#### Basic syntax
+
+A definition link looks as follows: `[[scala.collection.immutable.List]]`.
+
+Which is to say, a definition link is a sequence of identifiers separated by
+`.`. The identifiers can be separated with `#` as well for Scaladoc compatibility.
+
+By default, an identifier `id` references the first (in source order) entity
+named `id`. An identifier can end with `$`, which forces it to refer to a value
+(an object, a value, a given); an identifier can also end with `!`, which forces
+it to refer to a type (a class, a type alias, a type member).
+
+The links are resolved relative to the current location in source. That is, when
+documenting a class, the links are relative to the entity enclosing the class (a
+package, a class, an object); the same applies to documenting definitions.
+
+Special characters in links can be backslash-escaped, which makes them part of
+identifiers instead. For example, `` [[scala.collection.immutable\.List]] ``
+references the class named `` `immutable.List` `` in package `scala.collection`.
+
+#### New syntax
+
+We have extended Scaladoc definition links to make them a bit more pleasant to
+write and read in source. The new syntax features are:
 
 1. `package` can be used as a prefix to reference the enclosing package
     Example:
@@ -51,7 +77,7 @@ did, however, implement some improvements to it:
     Scaladoc required backslash-escaping to reference such identifiers. Instead,
     Scala3doc allows using the familiar Scala backtick quotation.
 
-### Why keep the Wiki syntax?
+#### Why keep the Wiki syntax for links?
 
 There are a few reasons why we've kept the Wiki syntax for documentation links
 instead of reusing the Markdown syntax. Those are:
@@ -67,4 +93,4 @@ instead of reusing the Markdown syntax. Those are:
 
 None of these make it completely impossible to use the standard Markdown link
 syntax, but they make it much more awkward and ugly than it needs to be. On top
-of that, Markdown link syntax doesn't even save any characters.
+of that, Markdown link syntax doesn't even save any characters.

docs/docs/usage/scala3doc/specificTags.md

@@ -1,29 +1,15 @@
 ---
-title: Dottydoc Specific Tags and Behavior
+title: Scala3doc-specific Tags and Features
 ---
 
 # {{page.title}}
 
-Scala3doc extends markdown with some unique behaviors such as linking to API. This can be used from within static documentation and blog posts to provide blend-in content.
+Scala3doc extends Markdown with additional features, such as linking
+to API definitions. This can be used from within static documentation and blog
+posts to provide blend-in content.
 
 ## Linking to API
 
-If you for instance, want to link to `scala.collection.immutable.Seq` in a
-markdown file, you can simply use the canonical path in your url:
-
-```markdown
-[Seq](scala.collection.immutable.Seq)
-```
-
-Linking to members is done in the same fashion:
-
-```markdown
-[Seq](scala.collection.immutable.Seq.isEmpty)
-```
-
-Scala3doc denotes objects by ending their names in "$". To select `List.range`
-you'd therefore write:
-
-```markdown
-[List.range](scala.collection.immutable.List$.range)
-```
+Scala3doc allows linking to API documentation with Wiki-style links. Linking to
+`scala.collection.immutable.List` is as simple as
+`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation](./docComments.html#definition-links).

scala3doc/src/dotty/dokka/site/common.scala

@@ -28,6 +28,7 @@ val defaultMarkdownOptions: DataHolder =
     .set(AnchorLinkExtension.ANCHORLINKS_WRAP_TEXT, false)
     .set(AnchorLinkExtension.ANCHORLINKS_ANCHOR_CLASS, "anchor")
     .set(EmojiExtension.ROOT_IMAGE_PATH, "https://github.global.ssl.fastly.net/images/icons/emoji/")
+    .set(WikiLinkExtension.LINK_ESCAPE_CHARS, "")
     .set(Parser.EXTENSIONS, java.util.Arrays.asList(
       TablesExtension.create(),
       TaskListExtension.create(),