RFR: 8303480: Miscellaneous fixes to mostly invisible doc comments
Pavel Rappo
prappo at openjdk.org
Fri Mar 3 09:41:06 UTC 2023
On Thu, 2 Mar 2023 16:23:17 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:
>> Please review this superficial documentation cleanup that was triggered by unrelated analysis of doc comments in JDK API.
>>
>> The only effect that this multi-area PR has on the JDK API Documentation (i.e. the observable effect on the generated HTML pages) can be summarized as follows:
>>
>>
>> diff -ur build/macosx-aarch64/images/docs-before/api/serialized-form.html build/macosx-aarch64/images/docs-after/api/serialized-form.html
>> --- build/macosx-aarch64/images/docs-before/api/serialized-form.html 2023-03-02 11:47:44
>> +++ build/macosx-aarch64/images/docs-after/api/serialized-form.html 2023-03-02 11:48:45
>> @@ -17084,7 +17084,7 @@
>> throws <span class="exceptions"><a href="java.base/java/io/IOException.html" title="class in java.io">IOException</a>,
>> <a href="java.base/java/lang/ClassNotFoundException.html" title="class in java.lang">ClassNotFoundException</a></span></div>
>> <div class="block"><code>readObject</code> is called to restore the state of the
>> - (@code BasicPermission} from a stream.</div>
>> + <code>BasicPermission</code> from a stream.</div>
>> <dl class="notes">
>> <dt>Parameters:</dt>
>> <dd><code>s</code> - the <code>ObjectInputStream</code> from which data is read</dd>
>>
>> Notes
>> -----
>>
>> * I'm not an expert in any of the affected areas, except for jdk.javadoc, and I was merely after misused tags. Because of that, I would appreciate reviews from experts in other areas.
>> * I discovered many more issues than I included in this PR. The excluded issues seem to occur in infrequently updated third-party code (e.g. javax.xml), which I assume we shouldn't touch unless necessary.
>> * I will update copyright years after (and if) the fix had been approved, as required.
>
> src/java.base/share/classes/java/lang/invoke/BootstrapMethodInvoker.java line 257:
>
>> 255:
>> 256: /**
>> 257: * @return true iff the BSM method type exactly matches
>
> I assume “iff” should “if”?
Here and elsewhere in this file "iff" might mean [if and only if](https://en.wikipedia.org/wiki/If_and_only_if), which would make sense. (FWIW, there are a few hundred occurrences of the word "iff" in src.)
@cl4es (Claes Redestad), as the author of those lines would you like to chime in?
Since Claes might read this, I note that when I changed unsupported `{@see}` to `{@link}` thoughtout this file, my IDE could not resolve one of the links: `java.lang.invoke.LambdaMetafactory#metafactory(MethodHandles.Lookup,String,Class,MethodType,MethodHandle,MethodType)`
While there's a similarly-name method with slightly different parameters, I refrained from using it:
`java.lang.invoke.LambdaMetafactory#metafactory(MethodHandles.Lookup,String,MethodType,MethodType,MethodHandle,MethodType)`.
-------------
PR: https://git.openjdk.org/jdk/pull/12826
More information about the ide-support-dev
mailing list