Add external mappings for scaladoc

[Flowdalic]

External mappings allow linking to other project's documentation, which makes it easier for users to understand the API.

This is a WIP. The main thing to address is that the place where we set scalaDocOptions may be not correct, I could imagine that it should be done in OsJvmModule. Furthermore, I should be only set if scaladoc from Scala 3 is used, as the -externalmappings` option is only available from there on. Unfortunately, I lack the mill and os-lib build system knowledge to proceed here. Any feedback would be appreciated.

[Flowdalic]

Updated change to include (ZincWorkerUtil.isDottyOrScala3(scalaVersion()) condition check. Thanks @lefou

[lefou]

Looks good to me. Is there no such option for Scala 2, or why do you just link when we build for Scala 3?

[SethTisue]

Scala 2 Scaladoc definitely supports source links; see for example the "Source: ..." link at https://www.scala-lang.org/api/2.13.11/scala/collection/immutable/List.html . it's via -doc-source-url

be careful about scala/bug#12867 though — a behavior changed between 2.13.11 and 2.13.12

[lefou]

Scala 2 Scaladoc definitely supports source links; see for example the "Source: ..." link at https://www.scala-lang.org/api/2.13.11/scala/collection/immutable/List.html . it's via -doc-source-url

be careful about scala/bug#12867 though — a behavior changed between 2.13.11 and 2.13.12

This PR isn't so much about source links but about cross-references to scaladoc of API dependencies.

E.g. The os.read.stream refers to Readable which comes from geny project.

[SethTisue]

Oh, sorry, I read too quickly.

But yes, Scala 2 Scaladoc has that too, via -doc-external-doc

[lefou]

Oh, sorry, I read too quickly.

But yes, Scala 2 Scaladoc has that too, via -doc-external-doc

Is there any documentation about it? I'm having a hard time to find more documentation or even the scaladoc cli usage. Even cs install scaladoc:2.13.12 isn't working. Scala 2.13 seems to be very legacy. ;D

[SethTisue]

Even cs install scaladoc:2.13.12 isn't working

Worked for me, just now, so maybe that could use its own ticket.

Is there any documentation about it?

scaladoc -help has:

  -doc-external-doc:<external-doc>            comma-separated list of classpath_entry_path#doc_URL pairs describing external dependencies.

It appears there otherwise isn't doc. https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html is where it should be, if it existed.

-doc-external-doc (formerly -doc-external-uris) is so old it goes back to when Scala was hardly more than a glimmer in Martin's eye, and nobody has documented it since afaict. GitHub search has a number of examples, though: https://github.com/search?q=-doc-external-doc&type=code . And https://github.com/ThoughtWorksInc/sbt-api-mappings is probably a source of knowhow, too.

[lefou]

I played a bit (probably an understatement) with -doc-external-doc and -jdk-api-doc-base, but both produced links to some URLs, but not the correct ones. I think we should just go with reference link in Scala 3 and be happy it works there reasonable. Thanks @SethTisue for you input.

[lefou]

Thank you, @Flowdalic !