8199176: Accessibility issues in java.base docs

Reviewed-by: lancea, alanb, jjg, rriggs

src/java.base/share/classes/java/lang/Runtime.java

@@ -1140,7 +1140,7 @@ public class Runtime {
          * number is not the major-release number but the feature-release
          * counter, incremented for every time-based release.  Use the {@link
          * #feature()} method in preference to this method.  For compatibility,
-         * this method returns the value of the <a href="FEATURE">feature</a>
+         * this method returns the value of the <a href="#FEATURE">feature</a>
          * element.
          *
          * @return The value of the feature element
@@ -1158,7 +1158,7 @@ public class Runtime {
          * number is not the minor-release number but the interim-release
          * counter, incremented for every interim release.  Use the {@link
          * #interim()} method in preference to this method.  For compatibility,
-         * this method returns the value of the <a href="INTERIM">interim</a>
+         * this method returns the value of the <a href="#INTERIM">interim</a>
          * element, or zero if it is absent.
          *
          * @return The value of the interim element, or zero
@@ -1176,7 +1176,7 @@ public class Runtime {
          * number is not the security level but the update-release counter,
          * incremented for every update release.  Use the {@link #update()}
          * method in preference to this method.  For compatibility, this method
-         * returns the value of the <a href="UPDATE">update</a> element, or
+         * returns the value of the <a href="#UPDATE">update</a> element, or
          * zero if it is absent.
          *
          * @return  The value of the update element, or zero
@@ -1188,9 +1188,9 @@ public class Runtime {
 
         /**
          * Returns an unmodifiable {@link java.util.List List} of the integers
-         * represented in the <a href="#verNum">version number</a>.  The {@code
+         * represented in the <a href="#verNum">version number</a>.
-         * List} always contains at least one element corresponding to the <a
+         * The {@code List} always contains at least one element corresponding to
-         * href="#feature">feature version number</a>.
+         * the <a href="#FEATURE">feature version number</a>.
          *
          * @return  An unmodifiable list of the integers
          *          represented in the version number

src/java.base/share/classes/java/lang/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -58,7 +58,7 @@
  * represent errors and exceptions.
  *
  * <a id="charenc"></a>
- * <h3>Character Encodings</h3>
+ * <h2>Character Encodings</h2>
  *
  * The specification of the {@link java.nio.charset.Charset
  * java.nio.charset.Charset} class describes the naming conventions

src/java.base/share/classes/java/nio/file/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2007, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -33,7 +33,7 @@
  * package is used by service provider implementors wishing to extend the
  * platform default provider, or to construct other provider implementations. </p>
  *
- * <h3><a id="links">Symbolic Links</a></h3>
+ * <h2><a id="links">Symbolic Links</a></h2>
  * <p> Many operating systems and file systems support for <em>symbolic links</em>.
  * A symbolic link is a special file that serves as a reference to another file.
  * For the most part, symbolic links are transparent to applications and
@@ -45,7 +45,7 @@
  * that are semantically close but support for these other types of links is
  * not included in this package. </p>
  *
- * <h3><a id="interop">Interoperability</a></h3>
+ * <h2><a id="interop">Interoperability</a></h2>
  * <p> The {@link java.io.File} class defines the {@link java.io.File#toPath
  * toPath} method to construct a {@link java.nio.file.Path} by converting
  * the abstract path represented by the {@code java.io.File} object. The resulting
@@ -54,7 +54,7 @@
  * on the <a href="Path.html#interop">interoperability</a> between {@code Path}
  * and {@code java.io.File} objects. </p>
  *
- * <h3>Visibility</h3>
+ * <h2>Visibility</h2>
  * <p> The view of the files and file system provided by classes in this package are
  * guaranteed to be consistent with other views provided by other instances in the
  * same Java virtual machine.  The view may or may not, however, be consistent with
@@ -65,7 +65,7 @@
  * or on some other machine.  The exact nature of any such inconsistencies are
  * system-dependent and are therefore unspecified. </p>
  *
- * <h3><a id="integrity">Synchronized I/O File Integrity</a></h3>
+ * <h2><a id="integrity">Synchronized I/O File Integrity</a></h2>
  * <p> The {@link java.nio.file.StandardOpenOption#SYNC SYNC} and {@link
  * java.nio.file.StandardOpenOption#DSYNC DSYNC} options are used when opening a file
  * to require that updates to the file are written synchronously to the underlying
@@ -82,7 +82,7 @@
  * java.nio.file.spi.FileSystemProvider provider} implementations is provider
  * specific. </p>
  *
- * <h3>General Exceptions</h3>
+ * <h2>General Exceptions</h2>
  * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
  * or method of any class or interface in this package will cause a {@link
  * java.lang.NullPointerException NullPointerException} to be thrown. Additionally,
@@ -103,7 +103,7 @@
  * provider} with a parameter that is an object created by another provider,
  * will throw {@link java.nio.file.ProviderMismatchException}. </p>
  *
- * <h3>Optional Specific Exceptions</h3>
+ * <h2>Optional Specific Exceptions</h2>
  * Most of the methods defined by classes in this package that access the
  * file system specify that {@link java.io.IOException} be thrown when an I/O
  * error occurs. In some cases, these methods define specific I/O exceptions

src/java.base/share/classes/java/time/chrono/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -95,7 +95,7 @@
  * <li>{@link java.time.chrono.ThaiBuddhistChronology Thai Buddhist calendar}</li>
  * </ul>
  *
- * <h3>Example</h3>
+ * <h2>Example</h2>
  * <p>
  * This example lists todays date for all of the available calendars.
  * </p>
@@ -155,7 +155,7 @@
  *                 first, last);
  *  </pre>
  *
- * <h3>Package specification</h3>
+ * <h2>Package specification</h2>
  * <p>
  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.

src/java.base/share/classes/java/time/format/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -79,7 +79,7 @@
  * {@link java.time.format.DecimalStyle DecimalStyle}.
  * </p>
  *
- * <h3>Package specification</h3>
+ * <h2>Package specification</h2>
  * <p>
  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.

src/java.base/share/classes/java/time/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -90,7 +90,7 @@
  * The calendar neutral API should be reserved for interactions with users.
  * </p>
  *
- * <h3>Dates and Times</h3>
+ * <h2>Dates and Times</h2>
  * <p>
  * {@link java.time.Instant} is essentially a numeric timestamp.
  * The current Instant can be retrieved from a {@link java.time.Clock}.
@@ -118,7 +118,7 @@
  * The widespread use of time-zones tends to add considerable complexity to an application.
  * </p>
  *
- * <h3>Duration and Period</h3>
+ * <h2>Duration and Period</h2>
  * <p>
  * Beyond dates and times, the API also allows the storage of periods and durations of time.
  * A {@link java.time.Duration} is a simple measure of time along the time-line in nanoseconds.
@@ -126,7 +126,7 @@
  * to humans, such as years or days.
  * </p>
  *
- * <h3>Additional value types</h3>
+ * <h2>Additional value types</h2>
  * <p>
  * {@link java.time.Month} stores a month on its own.
  * This stores a single month-of-year in isolation, such as 'DECEMBER'.
@@ -160,7 +160,7 @@
  * but contains less information than a full time-zone.
  * </p>
  *
- * <h3>Package specification</h3>
+ * <h2>Package specification</h2>
  * <p>
  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.
@@ -172,7 +172,7 @@
  * or a {@link java.time.DateTimeException}.
  * </p>
  *
- * <h3>Design notes (non normative)</h3>
+ * <h2>Design notes (non normative)</h2>
  * <p>
  * The API has been designed to reject null early and to be clear about this behavior.
  * A key exception is any method that takes an object and returns a boolean, for the purpose

src/java.base/share/classes/java/time/temporal/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -75,7 +75,7 @@
  * <li>Different definitions of weeks</li>
  * </ul>
  *
- * <h3>Fields and Units</h3>
+ * <h2>Fields and Units</h2>
  * <p>
  * Dates and times are expressed in terms of fields and units.
  * A unit is used to measure an amount of time, such as years, days or minutes.
@@ -106,7 +106,7 @@
  * The fields also provide access to the range of valid values.
  * </p>
  *
- * <h3>Adjustment and Query</h3>
+ * <h2>Adjustment and Query</h2>
  * <p>
  * A key part of the date-time problem space is adjusting a date to a new, related value,
  * such as the "last day of the month", or "next Wednesday".
@@ -131,7 +131,7 @@
  * Applications can also define queries by implementing {@link java.time.temporal.TemporalQuery}.
  * </p>
  *
- * <h3>Weeks</h3>
+ * <h2>Weeks</h2>
  * <p>
  * Different locales have different definitions of the week.
  * For example, in Europe the week typically starts on a Monday, while in the US it starts on a Sunday.
@@ -143,7 +143,7 @@
  * This is modeled in {@link java.time.temporal.IsoFields}.
  * </p>
  *
- * <h3>Package specification</h3>
+ * <h2>Package specification</h2>
  * <p>
  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.

src/java.base/share/classes/java/time/zone/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -70,7 +70,7 @@
  * gaps and overlaps in the local time-line typically caused by Daylight Saving Time.
  * </p>
  *
- * <h3>Package specification</h3>
+ * <h2>Package specification</h2>
  * <p>
  * Unless otherwise noted, passing a null argument to a constructor or method in any class or interface
  * in this package will cause a {@link java.lang.NullPointerException NullPointerException} to be thrown.

src/java.xml/share/classes/javax/xml/transform/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,7 +38,7 @@
  * {@link javax.xml.transform.stax}, and {@link javax.xml.transform.stream}.
  *
  *
- * <h3>Creating Objects</h3>
+ * <h2>Creating Objects</h2>
  *
  * <p>
  * The API allows a concrete {@link javax.xml.transform.TransformerFactory}
@@ -46,7 +46,7 @@
  * {@link javax.xml.transform.TransformerFactory#newInstance}.
  *
  *
- * <h3>Specification of Inputs and Outputs</h3>
+ * <h2>Specification of Inputs and Outputs</h2>
  *
  * <p>
  * This API defines two interface objects called {@link javax.xml.transform.Source}
@@ -77,9 +77,7 @@
  * </pre>
  *
  *
- * <h3>
+ * <h2><a id="qname-delimiter">Qualified Name Representation</a></h2>
- * <a id="qname-delimiter">Qualified Name Representation</a>
- * </h3>
  *
  * <p>
  * <a href="http://www.w3.org/TR/REC-xml-names">Namespaces</a> present something
@@ -112,7 +110,7 @@
  * prefix is lost.
  *
  *
- * <h3>Result Tree Serialization</h3>
+ * <h2>Result Tree Serialization</h2>
  *
  * <p>
  * Serialization of the result tree to a stream can be controlled with the
@@ -141,7 +139,7 @@
  * the source to the result. This method may be used to create a DOM from SAX
  * events or to create an XML or HTML stream from a DOM or SAX events.
  *
- * <h3>Exceptions and Error Reporting</h3>
+ * <h2>Exceptions and Error Reporting</h2>
  *
  * <p>
  * The transformation API throw three types of specialized exceptions. A
@@ -192,7 +190,7 @@
  * errors.
  *
  *
- * <h3>Resolution of URIs within a transformation</h3>
+ * <h2>Resolution of URIs within a transformation</h2>
  *
  * <p>
  * The API provides a way for URIs referenced from within the stylesheet

src/java.xml/share/classes/javax/xml/xpath/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -50,7 +50,7 @@
  * </ul>
  * <p>
  * <a id="XPath.Overview"></a>
- * <h3>1. XPath Overview</h3>
+ * <h2>1. XPath Overview</h2>
  *
  * <p>
  * The XPath language provides a simple, concise syntax for selecting
@@ -69,7 +69,7 @@
  *
  *
  * <a id="XPath.Expressions"></a>
- * <h3>2. XPath Expressions</h3>
+ * <h2>2. XPath Expressions</h2>
  *
  * <p>
  * An XPath <em>expression</em> is composed of a <em>location
@@ -211,7 +211,7 @@
  * </blockquote>
  *
  * <a id="XPath.Datatypes"></a>
- * <h3>3. XPath Data Types</h3>
+ * <h2>3. XPath Data Types</h2>
  *
  * <p>
  * While XPath expressions select nodes in the XML document, the XPath
@@ -225,7 +225,7 @@
  * </ul>
  *
  * <a id="XPath.Datatypes.QName"></a>
- * <h3>3.1 QName types</h3>
+ * <h2>3.1 QName types</h2>
  * The XPath API defines the following {@link javax.xml.namespace.QName} types to
  * represent return types of an XPath evaluation:
  * <ul>
@@ -258,7 +258,7 @@
  * of a node to a <code>double</code> data type.
  *
  * <a id="XPath.Datatypes.Class"></a>
- * <h3>3.2 Class types</h3>
+ * <h2>3.2 Class types</h2>
  * In addition to the QName types, the XPath API supports the use of Class types
  * through the <code>XPathExpression.evaluteExpression(...)</code> or
  * <code>XPath.evaluateExpression(...)</code> methods.
@@ -276,14 +276,14 @@
  * Of the subtypes of Number, only Double, Integer and Long are supported.
  *
  * <a id="XPath.Datatypes.Enum"></a>
- * <h3>3.3 Enum types</h3>
+ * <h2>3.3 Enum types</h2>
  * Enum types are defined in {@link javax.xml.xpath.XPathEvaluationResult.XPathResultType}
  * that provide mappings between the QName and Class types above. The result of
  * evaluating an expression using the <code>XPathExpression.evaluteExpression(...)</code>
  * or <code>XPath.evaluateExpression(...)</code> methods will be of one of these types.
  *
  * <a id="XPath.Context"></a>
- * <h3>4. XPath Context</h3>
+ * <h2>4. XPath Context</h2>
  *
  * <p>
  * XPath location paths may be relative to a particular node in the
@@ -301,7 +301,7 @@
  * {@link org.w3c.dom.Node} for example, in the JDK implementation.
  *
  * <a id="XPath.Use"></a>
- * <h3>5. Using the XPath API</h3>
+ * <h2>5. Using the XPath API</h2>
  *
  * Consider the following XML document:
  * <blockquote>