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]

Reply via email to