Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Scaladoc external references JDK11 #11839

Open
ashawley opened this issue Dec 28, 2019 · 16 comments
Open

Scaladoc external references JDK11 #11839

ashawley opened this issue Dec 28, 2019 · 16 comments

Comments

@ashawley
Copy link
Member

@ashawley ashawley commented Dec 28, 2019

Linking to Javadoc with JDK11 doesn't work in Scala 2.13.0-RC1 and later.

This is a build.sbt:

scalaVersion := "2.13.1"

scalacOptions in (Compile, doc) += "-Xfatal-warnings"

apiMappings ++= {
  Map(
    scalaInstance.value.libraryJar
      -> url(s"http://www.scala-lang.org/api/${scalaVersion.value}/")
  ) ++ Map(
    file("/modules/java.base")
      -> url("https://docs.oracle.com/en/java/javase/11/docs/api/java.base")
  )
}

A simple Scala file, A.scala:

/**
 * [[java.lang.Throwable]]
 * [[scala.AnyRef]]
 */
class A

Running doc in sbt:

[error] A.scala:1:1: Could not find any member to link for "java.lang.Throwable".
[error] /**
[error] ^
[error] one error found
[error] (Compile / doc) Scaladoc generation failed
@ashawley

This comment has been minimized.

Copy link
Member Author

@ashawley ashawley commented Dec 28, 2019

Repository with minimal example:

https://github.com/ashawley/scala-issue-11839

@ashawley

This comment has been minimized.

Copy link
Member Author

@ashawley ashawley commented Dec 28, 2019

A git bisect tracks it down to scala/scala#7782

It could be.

There is a reference to underlyingSource in scaladoc:

https://github.com/scala/scala/blob/2d9e6ac/src/scaladoc/scala/tools/nsc/doc/model/MemberLookup.scala#L61

@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 10, 2020

I'll take a look at it

@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 12, 2020

I have traced the problem to: https://github.com/scala/scala/blob/ba9701059216c629410f4f23a2175d20ad62484b/src/scaladoc/scala/tools/nsc/doc/model/MemberLookup.scala#L76

settings.extUrlMapping returns an empty Map. I do not know anything about Settings or how it is constructed...

@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 12, 2020

Alright, it is not a simple config, looking some more...

@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 15, 2020

I have a tentative fix, but I don't know enough about Java modules to know if this is correct.

steven-barnes/scala@66e2c25

The lookup is done using files with the .jmod suffix. In underlyingSource, we are pattern matching on the scheme, which AFAIK should be "jrt" and not "jmod", but this works... @retronym

@ashawley

This comment has been minimized.

Copy link
Member Author

@ashawley ashawley commented Jan 16, 2020

Is that change your guess, or did it fix the Scaladoc reference issue for you?

I built and published Scala locally with your branch, and I get the same error:

> ++2.13.2-bin-66e2c25!
[info] Forcing Scala version to 2.13.2-bin-66e2c25 on all projects.
[info] Reapplying settings...
> doc
[info] Updating ...
[info] Done updating.
[info] Main Scala API documentation to target/scala-2.13/api...
[info] Non-compiled module 'compiler-bridge_2.13' for Scala 2.13.2-bin-66e2c25. Compiling...
7 warnings
[info]   Compilation completed in 39.319s.
[error] A.scala:1:1: Could not find any member to link for "java.lang.Throwable".
[error] /**
[error] ^
[error] one error found
[error] (Compile / doc) Scaladoc generation failed
[error] Total time: 53 s, completed Jan 15, 2020, 5:14:22 PM

I'm on Mac OS X and using Java 11.0.2

$ java -version
java version "11.0.2" 2019-01-15 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.2+9-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.2+9-LTS, mixed mode)
@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 16, 2020

It does resolve the issue for me, although being a newbie I may be confused. I am using Mac OS X and Java 11.0.4

steve@Stevens-MBP scala-issue-11839 % sbt -Dstarr.version=2.13.2-bin-SNAPSHOT
[info] Loading global plugins from /Users/steve/.sbt/1.0/plugins
[info] Loading project definition from /Users/steve/dev/temp/scala-issue-11839/project
[info] Loading settings for project scala-issue-11839 from build.sbt ...
[info] Set current project to scala-issue-11839 (in build file:/Users/steve/dev/temp/scala-issue-11839/)
[info] sbt server started at local:///Users/steve/.sbt/1.0/server/21275a830197acab9eff/sock
sbt:scala-issue-11839> doc
[success] Total time: 0 s, completed Jan 15, 2020, 5:32:12 PM
sbt:scala-issue-11839> exit
[info] shutting down server
steve@Stevens-MBP scala-issue-11839 % java --version
java 11.0.4 2019-07-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.4+10-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.4+10-LTS, mixed mode)
steve@Stevens-MBP scala-issue-11839 %

@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 16, 2020

OK, does not fix the problem. I put a hack into my build.sbt, then removed it. Now that I do a clean build, the problem is back.

@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 16, 2020

I had manually set a mapping that worked:

file("/Library/Java/JavaVirtualMachines/jdk-11.0.4.jdk/Contents/Home/jmods/java.base.jmod") -> url("https://docs.oracle.com/en/java/javase/11/docs/api/java.base")

@ashawley

This comment has been minimized.

Copy link
Member Author

@ashawley ashawley commented Jan 16, 2020

Ok, thanks for double-checking.

@ashawley

This comment has been minimized.

Copy link
Member Author

@ashawley ashawley commented Jan 16, 2020

This is a difficult problem to work on because there isn't a good testing story with Scaladoc in the Scala build, and even more the case for JDK11 issues.

@ashawley

This comment has been minimized.

Copy link
Member Author

@ashawley ashawley commented Jan 16, 2020

% sbt -Dstarr.version=2.13.2-bin-SNAPSHOT

Oh, the starr.version trick will only work in the sbt build for Scala, and not for any sbt project, including my example repo.

@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 16, 2020

Is the lack of unit tests laziness, or difficulty?

@ashawley

This comment has been minimized.

Copy link
Member Author

@ashawley ashawley commented Jan 16, 2020

Yes, it is perhaps both. I'd phrase it that the Scaladoc is not a priority compared to the compiler or the standard library. However, it is also a complex tool that is difficult to test.

@steven-barnes

This comment has been minimized.

Copy link

@steven-barnes steven-barnes commented Jan 18, 2020

Alright, another attempt. steven-barnes/scala@d2ec0a5

I can attempt to write tests for some of this. Also test suites could be run with different JDKs, using a tool such as Jenkins

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.