daniellansun commented on code in PR #3312:
URL: https://github.com/apache/groovy/pull/3312#discussion_r4615688955
##########
subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/GroovyRootDocBuilder.java:
##########
@@ -100,6 +101,14 @@ public void buildTree(List<String> filenames) throws
IOException {
}
}
+ // the files are sorted to be processed in a reproducible order, the
package descriptions
+ // last once all the classes they may link to are known
+ filenames = new ArrayList<>(filenames);
+ filenames.sort(Comparator.comparing((String filename) ->
filename.endsWith("package.html")
+ ||
filename.endsWith("package-info.java")
+ ||
filename.endsWith("package-info.groovy"))
+ .thenComparing(Comparator.naturalOrder()));
Review Comment:
The "package descriptions last" half of this sort is the right fix for
`{@link}` resolution, but the `naturalOrder()` tie-breaker inside that group
makes `package.html` sort after `package-info.java` / `package-info.groovy` and
overwrite the package description. Javadoc prefers `package-info` when both
exist, and this repository already has that pair in five packages with
substantially different (and richer) `package-info` text —
`org.codehaus.groovy.classgen`'s `{@link AsmClassGenerator}` lives only in the
`package-info` file. Could this be a staged comparator instead, for example
ordinary sources, then `package.html`, then `package-info.*`, with
`naturalOrder()` only as an intra-stage tie-breaker? That would keep package
files after the classes they may link to, give `package-info` last-writer
precedence, and leave a clean later slot for `module-info.java` /
`module-info.groovy` if module groovydoc is added.
`endsWith("package-info.java")` does not match `module-info.java` tod
ay, which is what we want; those files can stay with ordinary sources until
that support exists.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]