For user-defined headings in Javadoc, start at <h2> (at class level) or <h4> (at method level).

android/guava/src/com/google/common/base/Converter.java

@@ -34,7 +34,7 @@
  * to {@code A}; used for converting back and forth between <i>different representations of the same
  * information</i>.
  *
- * <h3>Invertibility</h3>
+ * <h2>Invertibility</h2>
  *
  * <p>The reverse operation <b>may</b> be a strict <i>inverse</i> (meaning that {@code
  * converter.reverse().convert(converter.convert(a)).equals(a)} is always true). However, it is very
@@ -50,7 +50,7 @@
  * <p>Note that it should still be the case that the round-tripped and original objects are
  * <i>similar</i>.
  *
- * <h3>Nullability</h3>
+ * <h2>Nullability</h2>
  *
  * <p>A converter always converts {@code null} to {@code null} and non-null references to non-null
  * references. It would not make sense to consider {@code null} and a non-null reference to be
@@ -59,7 +59,7 @@
  * behavior for all converters; implementations of {@link #doForward} and {@link #doBackward} are
  * guaranteed to never be passed {@code null}, and must never return {@code null}.
  *
- * <h3>Common ways to use</h3>
+ * <h2>Common ways to use</h2>
  *
  * <p>Getting a converter:
  *
@@ -89,7 +89,7 @@
  *       be overridden.
  * </ul>
  *
- * <h3>Example</h3>
+ * <h2>Example</h2>
  *
  * {@snippet :
  * return Converter.from(

android/guava/src/com/google/common/base/Preconditions.java

@@ -57,7 +57,7 @@
  *
  * <p>would be flagged as having called {@code sqrt()} with an illegal argument.
  *
- * <h3>Performance</h3>
+ * <h2>Performance</h2>
  *
  * <p>Avoid passing message arguments that are expensive to compute; your code will always compute
  * them, even though they usually won't be needed. If you have such arguments, use the conventional
@@ -73,13 +73,13 @@
  * <p>As with any performance concerns, you should consider profiling your code (in a production
  * environment if possible) before spending a lot of effort on tweaking a particular element.
  *
- * <h3>Other types of preconditions</h3>
+ * <h2>Other types of preconditions</h2>
  *
  * <p>Not every type of precondition failure is supported by these methods. Continue to throw
  * standard JDK exceptions such as {@link java.util.NoSuchElementException} or {@link
  * UnsupportedOperationException} in the situations they are intended for.
  *
- * <h3>Non-preconditions</h3>
+ * <h2>Non-preconditions</h2>
  *
  * <p>It is of course possible to use the methods of this class to check for invalid conditions
  * which are <i>not the caller's fault</i>. Doing so is <b>not recommended</b> because it is
@@ -88,14 +88,14 @@
  * explained</a> in the Guava User Guide for more advice. Notably, {@link Verify} offers assertions
  * similar to those in this class for non-precondition checks.
  *
- * <h3>{@code java.util.Objects.requireNonNull()}</h3>
+ * <h2>{@code java.util.Objects.requireNonNull()}</h2>
  *
  * <p>Projects which use {@code com.google.common} should generally avoid the use of {@link
  * Objects#requireNonNull(Object)}. Instead, use whichever of {@link #checkNotNull(Object)} or
  * {@link Verify#verifyNotNull(Object)} is appropriate to the situation. (The same goes for the
  * message-accepting overloads.)
  *
- * <h3>Only {@code %s} is supported</h3>
+ * <h2>Only {@code %s} is supported</h2>
  *
  * <p>{@code Preconditions} uses {@link Strings#lenientFormat} to format error message template
  * strings. This only supports the {@code "%s"} specifier, not the full range of {@link
@@ -104,7 +104,7 @@
  * behave as expected, and will still include all argument values in the error message; the message
  * will simply not be formatted exactly as intended.
  *
- * <h3>More information</h3>
+ * <h2>More information</h2>
  *
  * <p>See the Guava User Guide on <a
  * href="https://github.com/google/guava/wiki/PreconditionsExplained">using {@code

android/guava/src/com/google/common/base/Verify.java

@@ -34,7 +34,7 @@
  *     "Unexpected bill status: %s", bill.status());
  * }
  *
- * <h3>Comparison to alternatives</h3>
+ * <h2>Comparison to alternatives</h2>
  *
  * <p><b>Note:</b> In some cases the differences explained below can be subtle. When it's unclear
  * which approach to use, <b>don't worry</b> too much about it; just pick something that seems
@@ -56,7 +56,7 @@
  *       same function with more clarity.
  * </ul>
  *
- * <h3>Warning about performance</h3>
+ * <h2>Warning about performance</h2>
  *
  * <p>Remember that parameter values for message construction must all be computed eagerly, and
  * autoboxing and varargs array creation may happen as well, even when the verification succeeds and
@@ -70,7 +70,7 @@
  * }
  * }
  *
- * <h3>Only {@code %s} is supported</h3>
+ * <h2>Only {@code %s} is supported</h2>
  *
  * <p>As with {@link Preconditions}, {@code Verify} uses {@link Strings#lenientFormat} to format
  * error message template strings. This only supports the {@code "%s"} specifier, not the full range
@@ -79,7 +79,7 @@
  * behave as expected, and will still include all argument values in the error message; the message
  * will simply not be formatted exactly as intended.
  *
- * <h3>More information</h3>
+ * <h2>More information</h2>
  *
  * See <a href="https://github.com/google/guava/wiki/ConditionalFailuresExplained">Conditional
  * failures explained</a> in the Guava User Guide for advice on when this class should be used.

android/guava/src/com/google/common/collect/BiMap.java

@@ -27,7 +27,7 @@
  * that of its keys. This constraint enables bimaps to support an "inverse view", which is another
  * bimap containing the same entries as this bimap but with reversed keys and values.
  *
- * <h3>Implementations</h3>
+ * <h2>Implementations</h2>
  *
  * <ul>
  *   <li>{@link ImmutableBiMap}

android/guava/src/com/google/common/collect/ClassToInstanceMap.java

@@ -31,7 +31,7 @@
  * <p>Like any other {@code Map<Class, Object>}, this map may contain entries for primitive types,
  * and a primitive type and its corresponding wrapper type may map to different values.
  *
- * <h3>Implementations</h3>
+ * <h2>Implementations</h2>
  *
  * <ul>
  *   <li>{@link ImmutableClassToInstanceMap}

android/guava/src/com/google/common/collect/Comparators.java

@@ -32,7 +32,7 @@
  * comparator utilities, see either {@code Comparator} itself (for Java 8+), or {@code
  * com.google.common.collect.Ordering} (otherwise).
  *
- * <h3>Relationship to {@code Ordering}</h3>
+ * <h2>Relationship to {@code Ordering}</h2>
  *
  * <p>In light of the significant enhancements to {@code Comparator} in Java 8, the overwhelming
  * majority of usages of {@code Ordering} can be written using only built-in JDK APIs. This class is

android/guava/src/com/google/common/collect/FluentIterable.java

@@ -62,7 +62,7 @@
  *
  * <p><a id="streams"></a>
  *
- * <h3>Comparison to streams</h3>
+ * <h2>Comparison to streams</h2>
  *
  * <p>Starting with Java 8, the core Java class libraries provide a new "Streams" library (in {@code
  * java.util.stream}), which is similar to {@code FluentIterable} but generally more powerful. Key
@@ -88,7 +88,7 @@
  *       under Android).
  * </ul>
  *
- * <h3>Example</h3>
+ * <h2>Example</h2>
  *
  * <p>Here is an example that accepts a list from a database call, filters it based on a predicate,
  * transforms it by invoking {@code toString()} on each element, and returns the first 10 elements

android/guava/src/com/google/common/collect/ImmutableCollection.java

@@ -50,12 +50,12 @@
  * ImmutableList}, which have well-defined {@link #equals} semantics, thus avoiding a common source
  * of bugs and confusion.
  *
- * <h3>About <i>all</i> {@code Immutable-} collections</h3>
+ * <h2>About <i>all</i> {@code Immutable-} collections</h2>
  *
  * <p>The remainder of this documentation applies to every public {@code Immutable-} type in this
  * package, whether it is a subtype of {@code ImmutableCollection} or not.
  *
- * <h4>Guarantees</h4>
+ * <h3>Guarantees</h3>
  *
  * <p>Each makes the following guarantees:
  *
@@ -76,7 +76,7 @@
  *       these guarantees to be violated).
  * </ul>
  *
- * <h4>"Interfaces", not implementations</h4>
+ * <h3>"Interfaces", not implementations</h3>
  *
  * <p>These are classes instead of interfaces to prevent external subtyping, but should be thought
  * of as interfaces in every important sense. Each public class such as {@link ImmutableSet} is a
@@ -98,7 +98,7 @@
  * {@link Collections#singleton(Object)} and {@link Set##unmodifiable Set.of}, we recommend using
  * <i>these</i> classes instead for this reason (as well as for consistency).
  *
- * <h4>Creation</h4>
+ * <h3>Creation</h3>
  *
  * <p>Except for logically "abstract" types like {@code ImmutableCollection} itself, each {@code
  * Immutable} type provides the static operations you need to obtain instances of that type. These
@@ -112,7 +112,7 @@
  *       instance.
  * </ul>
  *
- * <h4>Warnings</h4>
+ * <h3>Warnings</h3>
  *
  * <ul>
  *   <li><b>Warning:</b> as with any collection, it is almost always a bad idea to modify an element
@@ -122,7 +122,7 @@
  *       <i>deeply</i> immutable.
  * </ul>
  *
- * <h4>Performance notes</h4>
+ * <h3>Performance notes</h3>
  *
  * <ul>
  *   <li>Implementations can be generally assumed to prioritize memory efficiency, then speed of
@@ -142,7 +142,7 @@
  *       {@code hashCode} implementation, it should cache it itself.
  * </ul>
  *
- * <h4>Example usage</h4>
+ * <h3>Example usage</h3>
  *
  * {@snippet :
  * class Foo {
@@ -158,7 +158,7 @@
  * }
  * }
  *
- * <h3>See also</h3>
+ * <h2>See also</h2>
  *
  * <p>See the Guava User Guide article on <a href=
  * "https://github.com/google/guava/wiki/ImmutableCollectionsExplained">immutable collections</a>.

android/guava/src/com/google/common/collect/Multimap.java

@@ -52,7 +52,7 @@
  * times when the first style is more useful, use the multimap's {@link #asMap} view (or create a
  * {@code Map<K, Collection<V>>} in the first place).
  *
- * <h3>Example</h3>
+ * <h2>Example</h2>
  *
  * <p>The following code:
  *
@@ -77,7 +77,7 @@
  * ...
  * }
  *
- * <h3>Views</h3>
+ * <h2>Views</h2>
  *
  * <p>Much of the power of the multimap API comes from the <i>view collections</i> it provides.
  * These always reflect the latest state of the multimap itself. When they support modification, the
@@ -96,7 +96,7 @@
  * removeAll} methods, which contain values that have just been removed from the multimap, are
  * naturally <i>not</i> views.
  *
- * <h3>Subinterfaces</h3>
+ * <h2>Subinterfaces</h2>
  *
  * <p>Instead of using the {@code Multimap} interface directly, prefer the subinterfaces {@link
  * ListMultimap} and {@link SetMultimap}. These take their names from the fact that the collections
@@ -112,7 +112,7 @@
  * may not be equal and may or may not have the same {@code hashCode}. The recommended subinterfaces
  * provide much stronger guarantees.
  *
- * <h3>Comparison to a map of collections</h3>
+ * <h2>Comparison to a map of collections</h2>
  *
  * <p>Multimaps are commonly used in places where a {@code Map<K, Collection<V>>} would otherwise
  * have appeared. The differences include:
@@ -129,7 +129,7 @@
  *       Collections.min(multimap.values())} finds the smallest value across all keys.
  * </ul>
  *
- * <h3>Implementations</h3>
+ * <h2>Implementations</h2>
  *
  * <ul>
  *   <li>{@link ImmutableListMultimap}
@@ -142,7 +142,7 @@
  * new code, we recommend using {@link MultimapBuilder} instead: It provides better control of how
  * keys and values are stored.
  *
- * <h3>Other Notes</h3>
+ * <h2>Other Notes</h2>
  *
  * <p>As with {@code Map}, the behavior of a {@code Multimap} is not specified if key objects
  * already present in the multimap change in a manner that affects {@code equals} comparisons. Use

android/guava/src/com/google/common/collect/Multiset.java

@@ -64,7 +64,7 @@
  * element (in a way that affects its {@link Object#equals} behavior) while it is contained in a
  * multiset. Undefined behavior and bugs will result.
  *
- * <h3>Implementations</h3>
+ * <h2>Implementations</h2>
  *
  * <ul>
  *   <li>{@link ImmutableMultiset}

android/guava/src/com/google/common/collect/Ordering.java

@@ -56,12 +56,12 @@
  * of {@code Comparator} for pre-Java-8 users, in the same sense that {@link FluentIterable} is an
  * enriched {@link Iterable} for pre-Java-8 users.
  *
- * <h3>Three types of methods</h3>
+ * <h2>Three types of methods</h2>
  *
  * Like other fluent types, there are three types of methods present: methods for <i>acquiring</i>,
  * <i>chaining</i>, and <i>using</i>.
  *
- * <h4>Acquiring</h4>
+ * <h3>Acquiring</h3>
  *
  * <p>The common ways to get an instance of {@code Ordering} are:
  *
@@ -72,7 +72,7 @@
  *   <li>Use the natural ordering, {@link Ordering#natural}
  * </ul>
  *
- * <h4>Chaining</h4>
+ * <h3>Chaining</h3>
  *
  * <p>Then you can use the <i>chaining</i> methods to get an altered version of that {@code
  * Ordering}, including:
@@ -84,7 +84,7 @@
  *   <li>{@link #nullsFirst} / {@link #nullsLast}
  * </ul>
  *
- * <h4>Using</h4>
+ * <h3>Using</h3>
  *
  * <p>Finally, use the resulting {@code Ordering} anywhere a {@link Comparator} is required, or use
  * any of its special operations, such as:
@@ -95,7 +95,7 @@
  *   <li>{@link #min} / {@link #max}
  * </ul>
  *
- * <h3>Understanding complex orderings</h3>
+ * <h2>Understanding complex orderings</h2>
  *
  * <p>Complex chained orderings like the following example can be challenging to understand.
  *
@@ -125,14 +125,14 @@
  * encounter a call to {@code reverse}, continue working backwards until a result is determined, and
  * then reverse that result.
  *
- * <h3>Additional notes</h3>
+ * <h2>Additional notes</h2>
  *
  * <p>Except as noted, the orderings returned by the factory methods of this class are serializable
  * if and only if the provided instances that back them are. For example, if {@code ordering} and
  * {@code function} can themselves be serialized, then {@code ordering.onResultOf(function)} can as
  * well.
  *
- * <h3>Java 8+ users</h3>
+ * <h2>Java 8+ users</h2>
  *
  * <p>If you are using Java 8+, this class is now obsolete. Most of its functionality is now
  * provided by {@link java.util.stream.Stream Stream} and by {@link Comparator} itself, and the rest
@@ -145,7 +145,7 @@
  * code verbose. Whenever following this advice, you should check whether {@code Stream} could be
  * adopted more comprehensively in your code; the end result may be quite a bit simpler.
  *
- * <h3>See also</h3>
+ * <h2>See also</h2>
  *
  * <p>See the Guava User Guide article on <a href=
  * "https://github.com/google/guava/wiki/OrderingExplained">{@code Ordering}</a>.