4

In the documentation of my Scala project, I want to link to a member from an external Java library.

/**
 * Checks whether log entries at [[org.tinylog.Level.TRACE]] will be output.
 *
 * @return `true` if [[org.tinylog.Level.TRACE]] level is enabled, `false` if disabled
 */
def isTraceEnabled(): Boolean = macro TaggedLoggerMacro.isTraceEnabled

org.tinylog.Level.TRACE is an enum value from a Java project. IntelliJ can resolve all these links well, but scaladoc fails unfortunately.

My command:

C:\bin\java\jdk-9\bin\java -Xbootclasspath/a:C:\Users\martin\.m2\repository\org\scala-lang\scala-library\2.12.9\scala-library-2.12.9.jar;C:\Users\martin\.m2\repository\org\scala-lang\scala-compiler\2.12.9\scala-compiler-2.12.9.jar;C:\Users\martin\.m2\repository\org\scala-lang\scala-reflect\2.12.9\scala-reflect-2.12.9.jar;C:\Users\martin\.m2\repository\org\scala-lang\modules\scala-xml_2.12\1.0.6\scala-xml_2.12-1.0.6.jar;C:\Users\martin\.m2\repository\org\scala-lang\scala-library\2.12.0\scala-library-2.12.0.jar -classpath C:\Users\martin\.m2\repository\net\alchim31\maven\scala-maven-plugin\4.1.1\scala-maven-plugin-4.1.1.jar scala_maven_executions.MainWithArgsInFile scala.tools.nsc.ScalaDoc C:\data\martin\TEMP\scala-maven-14328178310010851042.args

My arguments:

-doc-external-doc
"C:\tinylog 2.0\tinylog-api\target\tinylog-api-2.1-SNAPSHOT.jar#https://tinylog.org/v2/javadoc/"
-classpath
C:\Users\martin\.m2\repository\org\scala-lang\scala-library\2.12.9\scala-library-2.12.9.jar;C:\Users\martin\.m2\repository\org\scala-lang\scala-reflect\2.12.9\scala-reflect-2.12.9.jar;C:\Users\martin\.m2\repository\org\tinylog\tinylog-api\2.1-SNAPSHOT\tinylog-api-2.1-SNAPSHOT.jar
-doc-format:html
-doc-title
"tinylog Scala API 2.1-SNAPSHOT API"
-d
"C:\tinylog 2.0\tinylog-api-scala\target\site\scaladocs"
"C:\tinylog 2.0\tinylog-api-scala\src\main\scala\org\tinylog\scala\Logger.scala"
"C:\tinylog 2.0\tinylog-api-scala\src\main\scala\org\tinylog\scala\LoggerMacro.scala"
"C:\tinylog 2.0\tinylog-api-scala\src\main\scala\org\tinylog\scala\TaggedLogger.scala"
"C:\tinylog 2.0\tinylog-api-scala\src\main\scala\org\tinylog\scala\TaggedLoggerMacro.scala"

Output (115 warnings in total):

C:\PROGS\dev\var\private\tinylog 2.0\tinylog-api-scala\src\main\scala\org\tinylog\scala\TaggedLogger.scala:242: warning: Could not find any member to link for "org.tinylog.Level.TRACE".
/**
    ^
C:\PROGS\dev\var\private\tinylog 2.0\tinylog-api-scala\src\main\scala\org\tinylog\scala\TaggedLogger.scala:229: warning: Could not find any member to link for "org.tinylog.Level.TRACE".
/**
    ^

How can I properly link to a member from an external Java library?

Martin
  • 598
  • 1
  • 4
  • 27
  • is this a `sbt` project? – pme Aug 26 '19 at 11:09
  • if I interpret this correctly it is not possible: https://www.scala-sbt.org/1.x/docs/Howto-Scaladoc.html#Select+javadoc+or+scaladoc – pme Aug 26 '19 at 11:24
  • The command and arguments are generated by scala-maven-plugin. – Martin Aug 26 '19 at 12:24
  • I'm afraid that you are right that linking is currently not possible. I just cannot believe that such a basic feature is not supported. – Martin Aug 26 '19 at 12:35
  • Is probably similar to this question: https://stackoverflow.com/questions/19786841/can-i-use-sbts-apimappings-setting-for-managed-dependencies/35673212#35673212 –  Aug 27 '19 at 14:38
  • The linked question is about linking to external Scala libraries. Unfortunately, the suggested solution does not work for linking to external Java libraries. – Martin Aug 29 '19 at 09:05

1 Answers1

4

As pme has mentioned in the comments, scaladoc does not support linking to Javadoc:

results from scaladoc not processing Javadoc comments in Java sources nor linking to Javadoc (https://www.scala-sbt.org/1.x/docs/Howto-Scaladoc.html)

Therefore, I have decided to use the full URLs for linking the enum values from my external Java library. This is not really convenient, but it works.

/**
 * Checks whether log entries at [[https://tinylog.org/v2/javadoc/org/tinylog/Level.html#TRACE TRACE]] will be output.
 *
 * @return `true` if [[https://tinylog.org/v2/javadoc/org/tinylog/Level.html#TRACE TRACE]] level is enabled, `false` if disabled
 */
def isTraceEnabled(): Boolean = macro LoggerMacro.isTraceEnabled

I see this as a workaround and not as an elegant solution. Any better solutions are welcome :)

Martin
  • 598
  • 1
  • 4
  • 27