Skip to content

Commit

Permalink
Work around Javadoc and JDiff bugs caused by the existence of two `co…
Browse files Browse the repository at this point in the history
…pyOf(E[])` declared in the same class.

(These methods already existed and already triggered the [Javadoc bug](https://bugs.openjdk.org/browse/JDK-8318093) (see, e.g., [`ImmutableSortedSet` for 32.1.3-jre](https://guava.dev/releases/32.1.3-jre/api/docs/com/google/common/collect/ImmutableSortedSet.html), but cl/572427348 caused them to trigger the more severe JDiff bug.)

Although those methods are legal overloads with different erasures, Javadoc gives them the same ID, "#copyOf(E%5B%5D)," so the links in the method summary both go to the same method's details. (Luckily, it's at least the method that people are likely to want.) Under newer versions of Javadoc than the one we use, Javadoc actually generates only one `copyOf(E[])` entry in the method summary! I hope it's the right one, but I haven't checked.

Additionally, JDiff has been [crashing](https://github.com/google/guava/actions/runs/6476993159/job/17586928450) during our doc-snapshot workflow since cl/572427348:

```
JDiff: reading the new API in from file '/tmp/guava-snapshot-temp.Dap/jre/Guava_HEAD-jre-SNAPSHOT.xml'...Error: duplicate comment id: com.google.common.collect.ImmutableSortedMultiset.copyOf_changed(E[])
```

So JDiff is making the same mistake as Javadoc.

Luckily, we can work around this by renaming the type parameter to "Z" in one case.

RELNOTES=n/a
PiperOrigin-RevId: 573801260
  • Loading branch information
cpovirk authored and Google Java Core Libraries committed Oct 16, 2023
1 parent cc3ed44 commit e029236
Show file tree
Hide file tree
Showing 4 changed files with 8 additions and 4 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -800,7 +800,8 @@ public static <E> ImmutableSortedMultiset<E> of(
*/
@DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
@Deprecated
public static <E> ImmutableSortedMultiset<E> copyOf(E[] elements) {
// The usage of "Z" here works around bugs in Javadoc (JDK-8318093) and JDiff.
public static <Z> ImmutableSortedMultiset<Z> copyOf(Z[] elements) {
throw new UnsupportedOperationException();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -893,7 +893,8 @@ public static <E> ImmutableSortedSet<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E
*/
@DoNotCall("Pass parameters of type Comparable")
@Deprecated
public static <E> ImmutableSortedSet<E> copyOf(E[] elements) {
// The usage of "Z" here works around bugs in Javadoc (JDK-8318093) and JDiff.
public static <Z> ImmutableSortedSet<Z> copyOf(Z[] elements) {
throw new UnsupportedOperationException();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -758,7 +758,8 @@ public static <E> ImmutableSortedMultiset<E> of(
*/
@DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
@Deprecated
public static <E> ImmutableSortedMultiset<E> copyOf(E[] elements) {
// The usage of "Z" here works around bugs in Javadoc (JDK-8318093) and JDiff.
public static <Z> ImmutableSortedMultiset<Z> copyOf(Z[] elements) {
throw new UnsupportedOperationException();
}
}
3 changes: 2 additions & 1 deletion guava/src/com/google/common/collect/ImmutableSortedSet.java
Original file line number Diff line number Diff line change
Expand Up @@ -997,7 +997,8 @@ public static <E> ImmutableSortedSet<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E
*/
@DoNotCall("Pass parameters of type Comparable")
@Deprecated
public static <E> ImmutableSortedSet<E> copyOf(E[] elements) {
// The usage of "Z" here works around bugs in Javadoc (JDK-8318093) and JDiff.
public static <Z> ImmutableSortedSet<Z> copyOf(Z[] elements) {
throw new UnsupportedOperationException();
}
}

0 comments on commit e029236

Please sign in to comment.