Clarify Scaladoc documentation on how to link to stdlib classes

Scaladoc is supposed to be able to link to classes of the standard library, as per the documentation (see [https://docs.scala-lang.org/style/scaladoc.html](Scaladoc style guide), section "General Style", 4th bullet:

Create links to referenced Scala Library classes using the square-bracket syntax, e.g. [[scala.Option]]

This doesn't work. I thought at first that the issue came from a problem with the dots that need escaping, or that maybe I needed to disambiguate between term and type, so I tried again with the following source:

package a

/**
 * Hello world,
 * [[scala.Option]]
 * [[scala.Option!]]
 * [[scala.Option$]]
 * [[scala\.Option]]
 * [[scala\.Option!]]
 * [[scala\.Option$]]
 * [[scala\\.Option]]
 * [[scala\\.Option!]]
 * [[scala\\.Option$]]
 */
object Foo

I'd have expected at least one of the links to work, but none of them resolved:

scaladoc ❯ scaladoc Bar.scala                                                 
model contains 3 documentable templates                                       
Bar.scala:3: warning: Could not find any member to link for "scala.Option".   
/**                                                                           
^                                                                             
Bar.scala:3: warning: Could not find any member to link for "scala.Option!".  
/**                                                                           
^                                                                             
Bar.scala:3: warning: Could not find any member to link for "scala.Option$".  
/**                                                                           
^                                                                             
Bar.scala:3: warning: Could not find any member to link for "scala\.Option".  
/**                                                                           
^                                                                             
Bar.scala:3: warning: Could not find any member to link for "scala\.Option!". 
/**                                                                           
^                                                                             
Bar.scala:3: warning: Could not find any member to link for "scala\.Option$". 
/**                                                                           
^                                                                             
Bar.scala:3: warning: Could not find any member to link for "scala\\.Option". 
/**                                                                           
^                                                                             
Bar.scala:3: warning: Could not find any member to link for "scala\\.Option!".
/**                                                                           
^                                                                             
Bar.scala:3: warning: Could not find any member to link for "scala\\.Option$".
/**                                                                           
^                                                                             
9 warnings found

Does this feature actually exist?

an example where it works is https://github.com/scala/scala-parser-combinators/blob/09c453acf32369389d67c8034b928510351879d9/shared/src/main/scala/scala/util/parsing/combinator/RegexParsers.scala#L20 , I ran doc locally and the resulting jvm/target/scala-2.12/api/scala/util/parsing/combinator/RegexParsers.html has the proper link to scala.Char

in that repo's build.sbt I see:

    apiMappings += (scalaInstance.value.libraryJar ->
        url(s"https://www.scala-lang.org/api/${scalaVersion.value}/")),

which I believe is what makes it work.

but see also https://github.com/ThoughtWorksInc/sbt-api-mappings which packages this up for you and supports other libraries as well

a scala/docs.scala-lang PR correcting the doc would be welcome

scala / docs.scala-lang

Clarify Scaladoc documentation on how to link to stdlib classes #1232