P4
One way to learn what a Value-based class is from the API Documentation, is to pick one of these classes and follow the link to the definition. The link is typically located in the standard verbiage, at the bottom of the class' top-level documentation, e.g.
"...This is a *value-based* class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of Optional may have unpredictable results and should be avoided...".
A disadvantage of this method is that you have to have a prior knowledge of at least a single class that is value-based.
Another way is to trivially use a link to the definition page. A disadvantage is that you have to have this link at hand.
----------
The discoverability of the Value-based class definition can be improved by adding the contents of the definition page to the API Documentation index. Consider the following patch (it also fixes a typo):
diff -r 5cf915f418f2 src/java.base/share/classes/java/lang/doc-files/ValueBased.html
--- a/src/java.base/share/classes/java/lang/doc-files/ValueBased.html Wed Nov 06 09:45:26 2019 -0800
+++ b/src/java.base/share/classes/java/lang/doc-files/ValueBased.html Thu Nov 07 13:46:14 2019 +0000
@@ -5,7 +5,7 @@
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
</head>
<body>
-<h1 id="ValueBased">Value-based Classes</h1>
+<h1 id="ValueBased">{@index "Value-based Classes"}</h1>
Some classes, such as <code>java.util.Optional</code> and
<code>java.time.LocalDateTime</code>, are <em>value-based</em>. Instances of a
@@ -23,7 +23,7 @@
<li>are considered equal solely based on <code>equals()</code>, not
based on reference equality (<code>==</code>);</li>
<li>do not have accessible constructors, but are instead instantiated
- through factory methods which make no committment as to the identity
+ through factory methods which make no commitment as to the identity
of returned instances;</li>
<li>are <em>freely substitutable</em> when equal, meaning that interchanging
any two instances <code>x</code> and <code>y</code> that are equal
"...This is a *value-based* class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of Optional may have unpredictable results and should be avoided...".
A disadvantage of this method is that you have to have a prior knowledge of at least a single class that is value-based.
Another way is to trivially use a link to the definition page. A disadvantage is that you have to have this link at hand.
----------
The discoverability of the Value-based class definition can be improved by adding the contents of the definition page to the API Documentation index. Consider the following patch (it also fixes a typo):
diff -r 5cf915f418f2 src/java.base/share/classes/java/lang/doc-files/ValueBased.html
--- a/src/java.base/share/classes/java/lang/doc-files/ValueBased.html Wed Nov 06 09:45:26 2019 -0800
+++ b/src/java.base/share/classes/java/lang/doc-files/ValueBased.html Thu Nov 07 13:46:14 2019 +0000
@@ -5,7 +5,7 @@
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
</head>
<body>
-<h1 id="ValueBased">Value-based Classes</h1>
+<h1 id="ValueBased">{@index "Value-based Classes"}</h1>
Some classes, such as <code>java.util.Optional</code> and
<code>java.time.LocalDateTime</code>, are <em>value-based</em>. Instances of a
@@ -23,7 +23,7 @@
<li>are considered equal solely based on <code>equals()</code>, not
based on reference equality (<code>==</code>);</li>
<li>do not have accessible constructors, but are instead instantiated
- through factory methods which make no committment as to the identity
+ through factory methods which make no commitment as to the identity
of returned instances;</li>
<li>are <em>freely substitutable</em> when equal, meaning that interchanging
any two instances <code>x</code> and <code>y</code> that are equal
- links to
