RFR: JDK-8261079: Fix support for @hidden in classes and interfaces

[Jonathan Gibbons]

On Thu, 4 Feb 2021 13:18:09 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> This change improves support for the `@hidden` tag to suppress documentation for specific elements, especially in the context of classes, interfaces and inheritance/method overriding.
> 
> The important changes are in `Utils` and in `VisibleMemberTable`. (There is also a number of non-related small code cleanup changes, sorry about that, I know it makes review a bit harder but I couldn't resist.)
> 
> In `Utils` the most important change are:
> 
>  - Consider types as "undocumented enclosures" if they are marked with a `@hidden` tag
>  - Check for `@hidden` tags even in non-included elements as they may be included via undocumented enclosures
>  - To counter the above change, only run doclint on elements that are either included or contained in an included type, as we don't want to report warnings or errors for non-included code. 
>  
> In `VisibleMemberTable` there is a subtle change to not consider an overriding method as a "simple override" if the overridden method is hidden or otherwise invisible but in turn is a non-simple override of a method further up the inheritance chain. This resulted in methods which should have been documented as declared locally to be documented as declared in supertypes. I also did a bit of renaming in `VisibleMemberTable` to make the purpose of things a bit clearer.
> 
> Other than that, most of the changes consist of added calls to `utils.hasHiddenTag(Element)`, usually with the purpose of not generating links to things that are not there.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 1567:

> 1565:         // prevent needless tests on elements which are neither included nor selected.
> 1566:         // Non-included members may still be visible via "transclusion" from undocumented enclusure
> 1567:         if (!isIncluded(e) && !configuration.docEnv.isSelected(e)) {

This comment applies to the whole of this method body.

I think the `@hidden` (or `@treatAsprivate`) tag is sufficiently special that it should be handled separately, especially in the cases where the containing comment would not otherwise be read, because the element is not included/selected. See other/earlier comments about avoiding `getDocComment` and going to the underlying `getDocCommentInfo`, which will (should?) completely bypass `getDocComment` and (importantly) the use of doclint.

-------------

PR: https://git.openjdk.java.net/jdk/pull/2406