Stale detection does not work: Javadoc generation is skipped when it should not

[anthonyvdotbe]

Affected version

3.12.0

Bug description

After changing the Javadoc in the Java source files and running mvn compile javadoc:javadoc again, Javadoc generation is skipped.

In maven-javadoc-plugin-stale-data.txt I see all the command-line arguments and then a bunch of lines like:

C:\path\to\target\reports\apidocs\allclasses-index.html = 1778834612169

I assume the right-hand side is a timestamp, but I'm surprised not to see a list of Java source files with timestamps? How can the plugin determine if something has changed if it only has the info in the maven-javadoc-plugin-stale-data.txt file?

Environment: Windows 11, JDK 26.0.1, Maven 3.9.15

[nmatt]

Same here, this is mystifying.

As a semi-workaround, one can force re-generation by configuring <staleDataPath>NUL</staleDataPath> on Windows or <staleDataPath>/dev/null</staleDataPath> on Unix (or use a Maven property set conditionally using a profile activated conditionally based on OS family).

[pedro-w]

I had a look at this.
Starting here

maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java

Lines 4973 to 4982 in 65b27eb

	private void executeJavadocCommandLine(Commandline cmd, File javadocOutputDirectory) throws MavenReportException {
	if (staleDataPath != null) {
	if (!isUpToDate(cmd)) {
	doExecuteJavadocCommandLine(cmd, javadocOutputDirectory);
	StaleHelper.writeStaleData(cmd, staleDataPath.toPath());
	}
	} else {
	doExecuteJavadocCommandLine(cmd, javadocOutputDirectory);
	}
	}

it does the up-to-date check and, if not stale, creates the javadoc then writes out the "stale data" - this means the current state of all options, source files, target files etc.
The up-to-date check checks the current state against whatever it last wrote out as "stale data" - if they are identical then it is up to date.

Next, getStaleData is here

maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/StaleHelper.java

Lines 47 to 96 in 65b27eb

	public static List<String> getStaleData(Commandline cmd) throws MavenReportException {
	try {
	List<String> ignored = new ArrayList<>();
	List<String> options = new ArrayList<>();
	Path dir = cmd.getWorkingDirectory().toPath().toAbsolutePath().normalize();
	String[] args = cmd.getArguments();
	Collections.addAll(options, args);
	for (String arg : args) {
	if (arg.startsWith("@")) {
	String name = arg.substring(1);
	options.addAll(Files.readAllLines(dir.resolve(name), EncodingUtils.getExpectedEncoding()));
	ignored.add(name);
	}
	}
	List<String> state = new ArrayList<>(options);
	boolean cp = false;
	boolean sp = false;
	for (String arg : options) {
	if (cp) {
	String s = unquote(arg);
	for (String ps : s.split(File.pathSeparator)) {
	Path p = dir.resolve(ps);
	state.add(p + " = " + lastmod(p));
	}
	} else if (sp) {
	String s = unquote(arg);
	for (String ps : s.split(File.pathSeparator)) {
	Path p = dir.resolve(ps);
	for (Path c : walk(p)) {
	if (Files.isRegularFile(c)) {
	state.add(c + " = " + lastmod(c));
	}
	}
	state.add(p + " = " + lastmod(p));
	}
	}
	cp = "-classpath".equals(arg);
	sp = "-sourcepath".equals(arg);
	}
	for (Path p : walk(dir)) {
	if (Files.isRegularFile(p) && !ignored.contains(p.getFileName().toString())) {
	state.add(p + " = " + lastmod(p));
	}
	}
	return state;
	} catch (Exception e) {
	throw new MavenReportException("Unable to compute stale date", e);
	}
	}

This is capturing the current state as I described above.
On line 73 and following is the source path handling. It splits up the paths into individual paths, and walks each one to pull out the file names in subdirectories. These are then all added to the state with their time stamps.

Unfortunately the function walk does not recursively check subdirs, only the toplevel.

maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/StaleHelper.java

Lines 115 to 125 in 65b27eb

	private static Collection<Path> walk(Path dir) {
	Collection<Path> paths = new ArrayList<>();
	try (DirectoryStream<Path> directoryStream = Files.newDirectoryStream(dir)) {
	for (Path p : directoryStream) {
	paths.add(p);
	}
	return paths;
	} catch (IOException e) {
	throw new RuntimeException(e);
	}
	}

The usual meaning of "walk" in the JDK is to recursively descend through the whole tree, e.g. java.nio.files.Files.walk(...)

So, I think it's a bug: source files are not considered when determining if the task needs redoing, because function org.apache.maven.plugins.javadoc.StaleHelper.walk does not include the whole tree of files that make up the source dir.

Edit: I've made a PR if that is useful

[anthonyvdotbe]

StaleHelper just doesn't cut it:

• what about --module-path, --patch-module, --module-source-path, ...?
• what about -docletpath and -docfilessubdirs?
• what about symbolic links?
• what about variants like --class-path, -cp, --source-path, -p, ...?
• what if the class path contains directories? (Maybe this won't ever occur in a Maven invocation, but still.)
• ...

Moreover, it has just one very basic test. And looking at the list of PRs doesn't inspire confidence that any PR will be reviewed in a timely manner.

So I propose to keep it simple/minimalistic and just rip out stale detection entirely.