Links generated by genjavadoc are broken

lightbend / genjavadoc

A compiler plugin for generating doc’able Java source from Scala source

Other

58 stars 32 forks source link

Links generated by genjavadoc are broken #43

Open hawkw opened 10 years ago

hawkw commented 10 years ago

I recently switched from using JavaDoc {@link ...} syntax in my ScalaDoc comments to using ScalaDoc [[..]] syntax, after learning that genjavadoc transforms ScalaDoc links into JavaDoc links. However, now, when I look at the JavaDoc html pages, the links appear as text rather than as links, and when generating JavaDoc, the JavaDoc tool prints a lot of warning - Tag @link: reference not found: warnings to the console.

I'm assuming that this is because the generated sources don't import the linked classes, is that correct?

I'm using Scala 2.11.2, and I'm running genjavadoc from a Gradle build script - I can post the Gradle build script if you like.

srowen commented 10 years ago

I find this as well, and also links that include a URL in [[...]]. I think these have to undergo more translation to be valid javadoc, and Java 8 flags them as errors not warnings.

patriknw commented 10 years ago

a pull request would be awesome ;-)

rkuhn commented 9 years ago

This is a current limitation: scaladoc comments are not parsed and interpreted , only minimal substitutions are made. This means that [[...]] syntax can only be used to link to Java classes. All other uses are illegal.

I mark this as an enhancement so that someone can pick it up if interested.

patriknw commented 6 years ago

Another thing to be careful with is [[methodName]] links. Those are not understood by genjavadoc. Intellij complains about [[#methodName]] syntax and you might replace them with [[methodName]].

[[#methodName]] and [[Class#methodName]] works fine. The latter is not a warning in Intellij.

tisonkun commented 4 years ago

@patriknw we don't support args in methodName yet? I try to write links like [[FileIO.toFile(File, util.Set[OpenOption])]] but it was rendered as <span class="extype" name="FileIO.toPath(Path,">util.Set[OpenOption])</span> which is neither a link nor a good display.