4

I want to compile javadoc for the testfx packages.

So I get hold of the source jars and extract (testfx-core-4.0.15-alpha-sources.jar, testfx-junit-4.0.15-alpha-sources.jar).

I find that all of these packages start "org.testfx....", so put them all together ... then I go:

mike@M17A ~/Desktop/temp $  javadoc -d docs -Xmaxwarns 10  -Xdoclint:none -sourcepath . -subpackages org

It lists 100 errors of the following type:

**  symbol:   class TextFlow
  location: class TextFlowMatchers
./org/testfx/matcher/control/TextFlowMatchers.java:157: error: cannot find symbol
    private static boolean hasText(TextFlow textFlow, String string) {
**

... and then stops. No Javadoc is produced! These are (obviously) classes which are outside the packages I'm trying to document. I don't want any hyperlinks for these, just write them out linkless, please.

NB I previously used another switch, -Xmaxerrs 10, in the command line. This simply limits the listing of errors to 10, but again the Javadoc itself is not produced.

This technique used to work. I have just upgraded (?) to Java 11. This appears to be new to Java 11. Anyone know how to overcome this nonsense?

later, in response to Slaw

I very much like to have local copies of reference documents of all the modules and frameworks and so on that I use, in all languages. I didn't know about the links to the online Javadoc. I could possibly use HTTrack to copy that particular website and make a local copy.

I did try the other route: cloning the git repo and running ./gradlew aggregateJavadoc. Unfortunately this failed:

mike@M17A ~/Desktop/temp2/TestFX $  ./gradlew aggregateJavadoc
> Task :aggregateJavadoc FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':aggregateJavadoc'.
> /home/mike/Desktop/temp2/TestFX/docs/javadoc does not exist

... before you ask, yes I tried creating a /javadoc folder there, but the task deleted it before then complaining again that it didn't exist!

I also tried the simple javadoc task. This also failed:

mike@M17A ~/Desktop/temp2/TestFX $  ./gradlew javadoc

> Task :testfx-core:compileModuleInfoJava
/home/mike/Desktop/temp2/TestFX/subprojects/testfx-core/src/main/java/module-info.java:37: 
warning: requires transitive directive for an automatic module
    requires transitive org.hamcrest;
                           ^
1 warning

> Task :testfx-core:javadoc FAILED
/home/mike/Desktop/temp2/TestFX/subprojects/testfx-core/src/main/java/module-info.java:36:
error: module not found: org.assertj.core
    requires static org.assertj.core;
                               ^
1 error

workaround

Fortunately I have managed to enlist the support of my Java 8 installation, which is still on my system, in my case: /usr/lib/jvm/java-8-openjdk-amd64/javadoc. Obviously I'll set up a symlink. Added benefit of using Java 8: I personally rather like the "frames" version of the Javadocs, i.e. with the packages and classes listed in the left-hand frames.

Conclusion

What could have led the brilliant people (not irony) behind Java to have modified things like this? I have looked quite carefully at the available switches and options for javadoc v. 11. Nothing enables you to make a simple, er, Javadoc, which in my naivety I had assumed was the purpose of the javadoc utility.

mike rodent
  • 14,126
  • 11
  • 103
  • 157
  • 3
    Have you tried just cloning the [repository](https://github.com/TestFX/TestFX) and running `./gradlew aggregateJavadoc`? That task is added to the root project by the root `build.gradle` file. Also, note the README of the repository links to the [online Javadoc](https://testfx.github.io/TestFX/docs/javadoc/) provided for the various subprojects. May I ask why you want to generate the Javadoc yourself? That said, you could try adding the JavaFX modules to the `--class-path` or `--module-path` to see if that solves the problem. – Slaw Sep 28 '19 at 23:13
  • Is there an updated version of jdk 11 that you aren't using? Perhaps you upgraded to something that isn't the latest. – Kaan Sep 29 '19 at 03:22
  • @Slaw thanks very much. Please see addition. I like having a local Javadoc (and other coding reference documents for all the languages I use) because of lookup speed (my Net connection can be quite bad at certain times of the day/week) and the ability to code offline. I'm not keen on using `--class-path` or `--module-path` as I'm using the javafx plugin (`id 'org.openjfx.javafxplugin' version '0.0.8'`) so in fact I don't set those paths at all. – mike rodent Sep 29 '19 at 12:35
  • @kaan Thanks. I'm using 11.0.4, which appears to be the latest for Java 11. I don't think it's likely that this will have been "corrected" in a later version: the trend has always been towards imposing ever more zealous constraints on use of this particular utility (doclint, etc.), so I would expect this to be the case also with Java 12, 13, etc. Mysteries beyond my paygrade and comprehension. – mike rodent Sep 29 '19 at 12:41
  • Hmm. Well, fixing the Gradle failure (by having the task create the directory after deleting it) `javadoc` still fails with multiple module errors ("_too many module declarations found_", "_module not found: _"). As I'm not familiar with the build environment of TestFX I don't know how to fix this problem (could be as simple as passing the appropriate property). That said, for this particular library, they do [upload the Javadoc JARs to Maven Central](https://repo1.maven.org/maven2/org/testfx/testfx-core/4.0.16-alpha/). You could download them manually and extract the contents. – Slaw Sep 29 '19 at 12:58
  • Thanks again ... got it from Maven Central. It's the version 8 "frames" version too. For other packages I'm happy to use the version 8 on my system until further notice. – mike rodent Sep 29 '19 at 13:05

0 Answers0