On Fri, 28 Oct 2022 16:46:24 GMT, Pavel Rappo <[email protected]> wrote:
>> Please have a look at this work-in-progress PR. The reason this is a
>> (normal) PR rather than a more suitable draft PR is to mainly trigger a
>> discussion on the mailing list on whether the suggested approach to solve
>> multiple intertwined issues of exception documentation inheritance is a
>> correct one.
>>
>> In a nutshell, it turns out that the combination of `{@throws}` and
>> `{@inheritDoc}` is quite complex. It's more complex than a combination of
>> `{@inheritDoc}` with any other tag or `{@inheritDoc}` on its own. To account
>> for that complexity, handling of `{@inheritDoc}` in `{@throws}` is lifted to
>> `ThrowsTaglet`.
>>
>> The said complexity stems from two facts:
>>
>> 1. Processing of `{@inheritDoc}` is context free and is done by replacing
>> `{@inheritDoc}` with the tags it expands to. That model does not account for
>> `@throws` where `{@inheritDoc}` sometimes expands to multiple `@throws`
>> tags, which correspond to _separate_ entries in the "Throws:" section of a
>> method detail. Read: we change the exception section, not a description of
>> one of its entries.
>>
>> 2. Corresponding exception types in the hierarchy (i.e. matching
>> `{@inheritDoc}` with exception documentation it must inherit) is not always
>> clear-cut. This becomes especially apparent when type variables are involved.
>>
>> History
>> -------
>>
>> The work started as an attempt to fix JDK-8285488, hence the issue number
>> for the PR. However, along its course the PR solved other issues, which will
>> be soon added to the PR:
>>
>> * 8287796: Stop auto-inheriting documentation for subclasses of exceptions
>> whose documentation is inherited
>> * 8291869: Match exceptions using types of `javax.lang.model`, not strings
>> * 8295277: Expand `{@inheritDoc}` in `@throws` fully
>> * 8288045: Clean up ParamTaglet
>> * 8288046: Clean up ThrowsTaglet
>>
>> As of today
>> -----------
>>
>> * All tests (both existing and newly introduced) pass.
>> * JDK API Documentation is the same, except for two files. In the first
>> file,
>> `docs/api/java.management.rmi/javax/management/remote/rmi/RMIConnectionImpl_Stub.html`,
>> the order of exceptions has changed, which is insignificant. As for the
>> second file, `docs/api/java.management/javax/management/MBeanServer.html`,
>> the new warning is generated and erroneous input added to the corresponding
>> page. The issue has to be addressed on the component side and is tracked by
>> JDK-8295151.
>
> Pavel Rappo has updated the pull request with a new target base due to a
> merge or a rebase. The pull request now contains 49 commits:
>
> - refactor: improve error handling
> - refactor: clarify, reuse, simplify, clean up
> - refactor: pass Utils & BaseConfiguration to taglet
>
> This simplifies lots of methods. Later this could be done for other
> taglets too.
> - refactor: better code comments
> - refactor: add more relevant excerpts from JLS
> - fix: introduce more control to search
>
> This is done for the sake of `@throws`. Two convenience methods are
> added to assist migration from Optional with minimal change to
> DocFinder call sites.
>
> This solves 8295800: When searching documentation for an exception,
> don't jump over methods that don't mention that exception.
> - refactor: clean up ThrowsTaglet
> - Merge branch 'master' into HEAD
> - fix: test failed due to filesystem handling issues
>
> Filed 8295543 to track that filesystem issue and fixed the test to make
> sure the package cannot be confused with the type parameter, whose
> name is not pertinent to the test anyway.
> - Merge branch 'master' into 8285488
> - ... and 39 more: https://git.openjdk.org/jdk/compare/628820f4...c2db1ae6
Jon, please don't waste your time reviewing this PR on per-commit basis. I
appreciate that, but it's neither necessary nor useful right now. Sorry if I
didn't make it clear during our brief coversation on this PR elsewhere.
Have a look at the end result (i.e. HEAD) and tell me if this PR is an
acceptable way to fix those seven issues (as of today) in the list.
-------------
PR: https://git.openjdk.org/jdk/pull/10746
