archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8305206: Add @spec tags in java.base/java.* (part 1)

Browse source 
Reviewed-by: alanb, naoto, darcy, lancea, dfuchs, iris, mchung
This commit is contained in:
Jonathan Gibbons 2023-04-04 00:09:38 +00:00
parent ccbb0e8d89
commit c6bd489cc8
60 changed files with 268 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

4
src/java.base/share/classes/java/util/Base64.java
View file

@ -73,6 +73,10 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
* method of this class will cause a {@link java.lang.NullPointerException
* NullPointerException} to be thrown.
*
* @spec https://www.rfc-editor.org/info/rfc2045
* RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies
* @spec https://www.rfc-editor.org/info/rfc4648
* RFC 4648: The Base16, Base32, and Base64 Data Encodings
* @author Xueming Shen
* @since 1.8
*/

1
src/java.base/share/classes/java/util/Currency.java
View file

@ -108,6 +108,7 @@ import sun.util.logging.PlatformLogger;
* with {@code Currency} or monetary values as it provides better handling of floating
* point numbers and their operations.
*
* @spec http://www.iso.org/iso/home/standards/currency_codes.htm ISO - ISO 4217 - Currency codes
* @see java.math.BigDecimal
* @since 1.4
*/

3
src/java.base/share/classes/java/util/Formatter.java
View file

@ -2010,6 +2010,9 @@ import sun.util.locale.provider.ResourceBundleBasedAdapter;
* method or constructor in this class will cause a {@link
* NullPointerException} to be thrown.
*
* @spec https://www.w3.org/TR/NOTE-datetime Date and Time Formats
* @spec https://www.rfc-editor.org/info/rfc822
* RFC 822: STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES
* @author Iris Clark
* @since 1.5
*/

9
src/java.base/share/classes/java/util/Locale.java
View file

@ -470,6 +470,10 @@ import sun.util.locale.provider.TimeZoneNameUtility;
* compatibility, the implementation still does not impose a length
* constraint.
*
* @spec https://www.rfc-editor.org/info/rfc4647
* RFC 4647: Matching of Language Tags
* @spec https://www.rfc-editor.org/info/rfc5646
* RFC 5646: Tags for Identifying Languages
* @see Builder
* @see ResourceBundle
* @see java.text.Format
@ -3036,6 +3040,7 @@ public final class Locale implements Cloneable, Serializable {
* </tbody>
* </table>
*
* @spec https://www.rfc-editor.org/info/rfc4647 RFC 4647: Matching of Language Tags
* @see #filter(List, Collection, FilteringMode)
* @see #filterTags(List, Collection, FilteringMode)
*
@ -3107,6 +3112,8 @@ public final class Locale implements Cloneable, Serializable {
* {@code "zh-Hant-*"} (Traditional Chinese, any regions) are extended
* language ranges.
*
* @spec https://www.rfc-editor.org/info/rfc4234 RFC 4234: Augmented BNF for Syntax Specifications: ABNF
* @spec https://www.rfc-editor.org/info/rfc4647 RFC 4647: Matching of Language Tags
* @see #filter
* @see #filterTags
* @see #lookup
@ -3303,6 +3310,7 @@ public final class Locale implements Cloneable, Serializable {
* @throws NullPointerException if {@code ranges} is null
* @throws IllegalArgumentException if a language range or a weight
* found in the given {@code ranges} is ill-formed
* @spec https://www.rfc-editor.org/info/rfc2616 RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
*/
public static List<LanguageRange> parse(String ranges) {
return LocaleMatcher.parse(ranges);
@ -3324,6 +3332,7 @@ public final class Locale implements Cloneable, Serializable {
* @throws NullPointerException if {@code ranges} is null
* @throws IllegalArgumentException if a language range or a weight
* found in the given {@code ranges} is ill-formed
* @spec https://www.rfc-editor.org/info/rfc2616 RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
* @see #parse(String)
* @see #mapEquivalents
*/

6
src/java.base/share/classes/java/util/Properties.java
View file

@ -986,6 +986,8 @@ public class Properties extends Hashtable<Object,Object> {
* @throws InvalidPropertiesFormatException Data on input stream does not
* constitute a valid XML document with the mandated document type.
* @throws NullPointerException if {@code in} is null.
*
* @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition)
* @see #storeToXML(OutputStream, String, String)
* @see <a href="http://www.w3.org/TR/REC-xml/#charencoding">Character
* Encoding in Entities</a>
@ -1064,6 +1066,8 @@ public class Properties extends Hashtable<Object,Object> {
* or if {@code encoding} is {@code null}.
* @throws ClassCastException if this {@code Properties} object
* contains any keys or values that are not {@code Strings}.
*
* @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition)
* @see #loadFromXML(InputStream)
* @see <a href="http://www.w3.org/TR/REC-xml/#charencoding">Character
* Encoding in Entities</a>
@ -1113,6 +1117,8 @@ public class Properties extends Hashtable<Object,Object> {
* @throws NullPointerException if {@code os} or {@code charset} is {@code null}.
* @throws ClassCastException if this {@code Properties} object
* contains any keys or values that are not {@code Strings}.
*
* @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition)
* @see #loadFromXML(InputStream)
* @see <a href="http://www.w3.org/TR/REC-xml/#charencoding">Character
* Encoding in Entities</a>

5
src/java.base/share/classes/java/util/UUID.java
View file

@ -68,6 +68,8 @@ import jdk.internal.access.SharedSecrets;
* Universally Unique IDentifier (UUID) URN Namespace</i></a>, section 4.2
* &quot;Algorithms for Creating a Time-Based UUID&quot;.
*
* @spec https://www.rfc-editor.org/info/rfc4122
* RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace
* @since 1.5
*/
public final class UUID implements java.io.Serializable, Comparable<UUID> {
@ -345,6 +347,9 @@ public final class UUID implements java.io.Serializable, Comparable<UUID> {
* </ul>
*
* @return The variant number of this {@code UUID}
*
* @spec https://www.rfc-editor.org/info/rfc4122
* RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace
*/
public int variant() {
// This field is composed of a varying number of bits.

3
src/java.base/share/classes/java/util/jar/Attributes.java
View file

@ -55,6 +55,7 @@ import sun.util.logging.PlatformLogger;
* <p>This map and its views have a predictable iteration order, namely the
* order that keys were inserted into the map, as with {@link LinkedHashMap}.
*
* @spec jar/jar.html JAR File Specification
* @author David Connelly
* @see Manifest
* @since 1.2
@ -446,6 +447,8 @@ public class Attributes implements Map<Object,Object>, Cloneable {
* and will be UTF8-encoded when written to the output stream. See the
* <a href="{@docRoot}/../specs/jar/jar.html">JAR File Specification</a>
* for more information about valid attribute names and values.
*
* @spec jar/jar.html JAR File Specification
*/
public static class Name {
private final String name;

1
src/java.base/share/classes/java/util/jar/Manifest.java
View file

@ -44,6 +44,7 @@ import sun.security.util.SecurityProperties;
* <a href="{@docRoot}/../specs/jar/jar.html">
* Manifest format specification</a>.
*
* @spec jar/jar.html JAR File Specification
* @author David Connelly
* @see Attributes
* @since 1.2

1
src/java.base/share/classes/java/util/jar/package-info.java
View file

@ -44,6 +44,7 @@
* Manifest and Signature Specification</a> - The manifest format specification.
* </ul>
*
* @spec jar/jar.html JAR File Specification
* @since 1.2
*/
package java.util.jar;

3
src/java.base/share/classes/java/util/regex/Pattern.java
View file

@ -784,6 +784,7 @@ import jdk.internal.util.regex.Grapheme;
* O'Reilly and Associates, 2006.</a>
* </p>
*
* @spec https://www.unicode.org/reports/tr18 Unicode Regular Expressions
* @see java.lang.String#split(String, int)
* @see java.lang.String#split(String)
*
@ -939,6 +940,8 @@ public final class Pattern
* folding.
* <p>
* Specifying this flag may impose a performance penalty. </p>
*
* @spec https://www.unicode.org/reports/tr18 Unicode Regular Expressions
* @since 1.7
*/
public static final int UNICODE_CHARACTER_CLASS = 0x100;

2
src/java.base/share/classes/java/util/spi/TimeZoneNameProvider.java
View file

@ -74,6 +74,8 @@ public abstract class TimeZoneNameProvider extends LocaleServiceProvider {
* getAvailableLocales()}.
* @throws NullPointerException if {@code ID} or {@code locale}
* is null
*
* @spec https://www.iana.org/time-zones Time Zone Database
* @see java.util.TimeZone#getDisplayName(boolean, int, java.util.Locale)
*/
public abstract String getDisplayName(String ID, boolean daylight, int style, Locale locale);

2
src/java.base/share/classes/java/util/zip/CRC32C.java
View file

@ -47,6 +47,8 @@ import static java.util.zip.ZipUtils.NIO_ACCESS;
* {@link NullPointerException} to be thrown.
* </p>
*
* @spec https://www.rfc-editor.org/info/rfc3720
* RFC 3720: Internet Small Computer Systems Interface (iSCSI)
* @since 9
*/
public final class CRC32C implements Checksum {

8
src/java.base/share/classes/java/util/zip/package-info.java
View file

@ -72,6 +72,14 @@
* <li>Adler-32 checksum is described in RFC 1950 (above)
* </ul>
*
* @spec https://www.rfc-editor.org/info/rfc1950
* RFC 1950: ZLIB Compressed Data Format Specification version 3.3
* @spec https://www.rfc-editor.org/info/rfc1951
* RFC 1951: DEFLATE Compressed Data Format Specification version 1.3
* @spec https://www.rfc-editor.org/info/rfc1952
* RFC 1952: GZIP file format specification version 4.3
* @spec https://www.rfc-editor.org/info/rfc3720
* RFC 3720: Internet Small Computer Systems Interface (iSCSI)
* @since 1.1
*/
package java.util.zip;