[notes] 01/01: update timestamps_in_documentation_generated_by_javadoc note

[Chris West]

This is an automated email from the git hooks/post-receive script.

faux-guest pushed a commit to branch master
in repository notes.

commit 0c27242c5414a3e7da049da48a44f302157baaff
Author: Chris West (Faux) <git at goeswhere.com>
Date:   Tue Apr 11 15:15:21 2017 +0100

    update timestamps_in_documentation_generated_by_javadoc note
---
 issues.yml | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/issues.yml b/issues.yml
index 79fd20f..1b6871d 100644
--- a/issues.yml
+++ b/issues.yml
@@ -254,16 +254,28 @@ timestamps_in_documentation_generated_by_javadoc:
   deterministic: True
 random_order_in_documentation_generated_by_javadoc:
   description: |
-    The `package-tree.html` file generated by javadoc contains an unsorted index.
+    Some entries inside individual documentation pages are emitted in different oredrs.
+    This appears to only happen with multi-module maven projects, i.e. possibly during
+    `mvn javadoc:aggregate`.
+    .
+    Historically, there were some other issues. These have disappeared, but it's not clear why.
+    The major version of OpenJDK has changed since these issues were reported (was 7, now 8),
+    although the code that was believed to be at fault remains unchanged.
     .
-    There is also a locale-specific wrapping issue. This tag might need splitting
+    The `package-tree.html` file generated by javadoc contains an unsorted index.
     .
-    Likely cause of the former is that packageFiles is a Map<String, List<JavaFileObject>> in
+    Perhaps caused by packageFiles is a Map<String, List<JavaFileObject>> in
     openjdk-7-jdk -> ./langtools.tar.bz2 ->
     src/share/classes/com/sun/tools/javadoc/JavadocTool.java
     .
-    Likely cause of the latter is
+    There was also a locale-specific wrapping issue, which has disappeared.
+    This may be because enough things are using javahelper, which sets the locale.
+    .
+    Likely cause is
     jdk9_dev/langtools/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/DocLocale.java +172
+    .
+    Workaround is
+    https://sources.debian.net/src/maven-debian-helper/2.1.3/share/cdbs/1/class/maven.mk/?hl=136#L136
 method_may_never_be_called_in_documentation_generated_by_javadoc:
   description: |
     javadoc can add "This method may never be called" in some builds and not

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/notes.git