Skip to content

Commit

Permalink
Correct Javadoc warnings, prevent future ones (#3898)
Browse files Browse the repository at this point in the history
Addresses several classes of issues, some in more than one way:
* Ensure all javadoc runs use UTF-8 encoding, and remove non-ASCII chars which are intended to be interpreted as code
* HTML-encode characters that must be encoded in javadoc, and correct wrongly-encoded chars.
* Don't reference JVM internals that can't be linked, instead refer to them as @code.
* Fixed mismatched html tags, broken attrs.
* Corrected/removed classes/members that don't exist or can't be referenced in that way.

Fixes #1513
  • Loading branch information
niloc132 authored Jun 2, 2023
1 parent a4676d8 commit 4c5fc89
Show file tree
Hide file tree
Showing 83 changed files with 421 additions and 420 deletions.
20 changes: 2 additions & 18 deletions .github/workflows/docs-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,6 @@ jobs:
distribution: 'temurin'
java-version: '11'

# TODO(deephaven-core#1513): Remove non-LTS JDK 15 as part of javadocs process
- name: Setup JDK 15
id: setup-java-15
uses: actions/setup-java@v3
with:
distribution: 'zulu'
java-version: '15'

- name: Setup JDK 17
id: setup-java-17
uses: actions/setup-java@v3
Expand All @@ -42,7 +34,7 @@ jobs:
run: |
cat .github/env/${{ runner.os }}/gradle.properties >> gradle.properties
echo >> gradle.properties
echo "org.gradle.java.installations.paths=${{ steps.setup-java-11.outputs.path }},${{ steps.setup-java-15.outputs.path }},${{ steps.setup-java-17.outputs.path }}" >> gradle.properties
echo "org.gradle.java.installations.paths=${{ steps.setup-java-11.outputs.path }},${{ steps.setup-java-17.outputs.path }}" >> gradle.properties
cat gradle.properties
- name: All Javadoc
Expand Down Expand Up @@ -84,14 +76,6 @@ jobs:
distribution: 'temurin'
java-version: '11'

# TODO(deephaven-core#1513): Remove non-LTS JDK 15 as part of javadocs process
- name: Setup JDK 15
id: setup-java-15
uses: actions/setup-java@v3
with:
distribution: 'zulu'
java-version: '15'

- name: Setup JDK 17
id: setup-java-17
uses: actions/setup-java@v3
Expand All @@ -106,7 +90,7 @@ jobs:
run: |
cat .github/env/${{ runner.os }}/gradle.properties >> gradle.properties
echo >> gradle.properties
echo "org.gradle.java.installations.paths=${{ steps.setup-java-11.outputs.path }},${{ steps.setup-java-15.outputs.path }},${{ steps.setup-java-17.outputs.path }}" >> gradle.properties
echo "org.gradle.java.installations.paths=${{ steps.setup-java-11.outputs.path }},${{ steps.setup-java-17.outputs.path }}" >> gradle.properties
cat gradle.properties
- name: Generate Python Docs
Expand Down
2 changes: 1 addition & 1 deletion Base/src/main/java/io/deephaven/base/ArrayUtil.java
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ public class ArrayUtil {

/**
* The maximum array size is determined by the JVM and in practice is less than Integer.MAX_VALUE. (See note at
* {@link jdk.internal.util.ArraysSupport#SOFT_MAX_ARRAY_LENGTH}.)
* {@code jdk.internal.util.ArraysSupport#SOFT_MAX_ARRAY_LENGTH}.)
*/
// We would like to use jdk.internal.util.ArraysSupport.MAX_ARRAY_LENGTH, but it is not exported
public static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;
Expand Down
8 changes: 4 additions & 4 deletions Base/src/main/java/io/deephaven/base/CompareUtils.java
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ public static boolean doubleEquals2(double x, double y, double tolerance) {
}

/**
* Since logical comparison of double values considerig error is effectively a three-value logic, you can't really
* Since logical comparison of double values considering error is effectively a three-value logic, you can't really
* do !equals when you mean notEquals.
*
* @param x
Expand Down Expand Up @@ -159,7 +159,7 @@ public static boolean doubleNotEquals2(double x, double y, double tolerance) {
}

/**
* You can't do double1 > double2 because floating point numbers are not exact values. Just make sure that x-y is
* You can't do double1 > double2 because floating point numbers are not exact values. Just make sure that x-y is
* greater than some allowable error factor for equality
*
* @param x
Expand Down Expand Up @@ -191,8 +191,8 @@ public static boolean doubleGreaterEqual(double x, double y, double tolerance) {
}

/**
* You can't do double1 < double2 because floating point numbers are not exact values. Just make sure that y - x is
* greater than some allowable error factor for equality
* You can't do double1 &lt; double2 because floating point numbers are not exact values. Just make sure that y - x
* is greater than some allowable error factor for equality
*
* @param x
* @param y
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
* when expanding). This set only has one {@link Iterator}, which is reused. This set is not thread safe.
* <P>
* Note: This class extends {@link HashMap} rather than {@link Map} (or {@link AbstractMap}) only because one of the
* fields where we want to use it ({@link sun.nio.ch.EPollSelectorImpl#fdToKey}) is (improperly) declared as a HashMap
* fields where we want to use it ({@code sun.nio.ch.EPollSelectorImpl#fdToKey}) is (improperly) declared as a HashMap
* rather than a Map.
*/
public class LowGarbageArrayIntegerMap<T> extends HashMap<Integer, T> {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
* expanding). This set only has one {@link Iterator}, which is reused. This set is not thread safe.
* <P>
* Note: This class extends {@link HashSet} rather than {@link Set} (or {@link AbstractSet}) only because one of the
* fields where we want to use it ({@link sun.nio.ch.SelectorImpl#keys}) is (improperly) declared as a HashSet rather
* fields where we want to use it ({@code sun.nio.ch.SelectorImpl#keys}) is (improperly) declared as a HashSet rather
* than a Set.
*/
public class LowGarbageArraySet<T> extends HashSet<T> {
Expand Down
6 changes: 3 additions & 3 deletions Base/src/main/java/io/deephaven/base/MathUtil.java
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ public static int gcd(int a, int b) {
};

/**
* Compute 10^n as a int for 0 <= n <= 9.
* Compute 10^n as a int for 0 &lt;= n &lt;= 9.
*
* @param n the exponent
* @return 10^n
Expand All @@ -95,9 +95,9 @@ public static int pow10(int n) {
};

/**
* Compute the number of base 10 digits in n's representation, for n >= 0.
* Compute the number of base 10 digits in n's representation, for n &gt;= 0.
*
* @param n an integer >= 0
* @param n an integer &gt;= 0
* @return how many digits in n's base 10 representation.
*/
public static int base10digits(int n) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ public interface Adapter<INPUT_TYPE, OUTPUT_TYPE> {
int hashCode(@NotNull final INPUT_TYPE inputItem);

/**
* Note: The following must be true: hashCode(inputItem) == outputItem.hashCode() && equals(inputItem,
* Note: The following must be true: hashCode(inputItem) == outputItem.hashCode() &amp;&amp; equals(inputItem,
* outputItem)
*
* @param inputItem The input item
Expand Down
2 changes: 1 addition & 1 deletion Base/src/main/java/io/deephaven/base/stats/Group.java
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ public Item[] getItems() {
}

/**
* Update the histories of all items in this group, logging all updated intervals >= logInterval.
* Update the histories of all items in this group, logging all updated intervals &gt;= logInterval.
*/
public void update(ItemUpdateListener listener, long logInterval, long now, long appNow) {
Item[] arr = itemsArray;
Expand Down
2 changes: 1 addition & 1 deletion Base/src/main/java/io/deephaven/base/stats/Item.java
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ public String getCompactName() {
}

/**
* Update the history intervals for this item's value, logging updated intervals >= logInterval
* Update the history intervals for this item's value, logging updated intervals &gt;= logInterval
*/
public void update(ItemUpdateListener listener, long logInterval, long now, long appNow) {
value.update(this, listener, logInterval, now, appNow);
Expand Down
2 changes: 1 addition & 1 deletion Base/src/main/java/io/deephaven/base/stats/Stats.java
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ public synchronized static Group getGroup(String name) {
}

/**
* Update the histories of all items in all groups, logging all updated intervals >= logInterval.
* Update the histories of all items in all groups, logging all updated intervals &gt;= logInterval.
*/
public synchronized static void update(ItemUpdateListener listener, long now, long appNow, long logInterval) {
for (Group g : groups) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,8 @@ public String getEncodingName() {
}

/**
* Can this encoding info's charset be encoded or decoded by simple linear assignment of char->byte or byte->char.
* Can this encoding info's charset be encoded or decoded by simple linear assignment of char-&gt;byte or
* byte-&gt;char.
*
* @return Whether this encoding info's charset is simple
*/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
/**
* This is a ridiculously simple, light-as-I-can-make-it, but decidedly single-purpose data structure. Specifically,
* it's a CompressedString with an embedded (to avoid reference or Object instance overhead) open-addressed
* SimpleReference<Object>-identity -> int hash map with load factor 1 (100%) and no public operations other than
* "putIfAbsent".
* SimpleReference&lt;Object&gt;-identity -&gt; int hash map with load factor 1 (100%) and no public operations other
* than "putIfAbsent".
*
* The reason for requiring that key objects be SimpleReferences is to allow for O(1) automatic slot reclamation across
* many MappedCompressedString instances at the same time. A given source of mappings creates a single SimpleReference
Expand All @@ -23,8 +23,9 @@
*
* Unfortunately, I haven't figured out a way to make this allow concurrent gets.
*
* The intended use is in Deephaven import code, for storing SymbolManager -> SymbolId mappings on the CompressedString
* that represents the Symbol itself, typically inside of a (bounded) StringCache of MappedCompressedString instances.
* The intended use is in Deephaven import code, for storing SymbolManager -&gt; SymbolId mappings on the
* CompressedString that represents the Symbol itself, typically inside of a (bounded) StringCache of
* MappedCompressedString instances.
*
* Note that this uses io.deephaven.base.reference.SimpleReference instead of java.lang.ref.Reference so that unit tests
* can avoid being required to use the concrete sub-classes of Reference, which all come with GC-related side-effects.
Expand Down Expand Up @@ -92,7 +93,7 @@ public final synchronized int capacity() {
}

/**
* Add the specified <key, value> pair if no mapping already exists for key.
* Add the specified &lt;key, value&gt; pair if no mapping already exists for key.
*
* @param key A non-null Reference to an arbitrary object whose reachability determines mapping validity.
* @param potentialValue The value to insert if none already exists. Must not equal NULL_MAPPING_VALUE.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ public interface StringCache<STRING_LIKE_TYPE extends CharSequence> {
/**
* Get a hint about this cache's capacity and behavior.
*
* @return -1 : This is an unbounded cache. 0 : This "cache" doesn't actually perform any caching. >0 : Actual
* @return -1 : This is an unbounded cache. 0 : This "cache" doesn't actually perform any caching. &gt;0 : Actual
* capacity bound.
*/
int capacity();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ public interface StringCompatible extends CharSequence, Comparable<CharSequence>
/**
* Implementations MUST compare StringCompatibles and Strings char-by-char.
*
* @return 0, <0, or >0 if that compares equal-to, less-than, or greater-than this.
* @return 0, &lt;0, or &gt;0 if that compares equal-to, less-than, or greater-than this.
*/
@Override
int compareTo(@NotNull final CharSequence that);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ public static void exitUncaught(Thread thread, Throwable throwable, int status,
}

/**
* Equivalent to {@code exitCaught(thread, throwable, status, out, null).
* Equivalent to {@code exitCaught(thread, throwable, status, out, null)}.
*/
public static void exitCaught(Thread thread, Throwable throwable, int status, PrintStream out) {
exitCaught(thread, throwable, status, out, null);
Expand Down
Loading

0 comments on commit 4c5fc89

Please sign in to comment.