RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v5]

[Pavel Rappo]

On Mon, 6 Jun 2022 20:40:18 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 35 commits:
>> 
>>  - Merge branch 'master' into 8287333
>>    
>>    It's two days before RDP1, the codebase changes quickly. This merge is to keep up with it.
>>  - Address feedback
>>    
>>    Also removes unneeded import.
>>  - Merge branch 'master' into 8287333
>>    
>>    This resolves a conflict in ParamTaglet.
>>  - Clean up if-branch
>>  - Remove upper-bounded wildcard
>>    
>>    This change simplifies code without any disadvantages:
>>    
>>      * Those `List<? extends XTree>` are read-only
>>      * An argument of the `List<XTree>` type can still be passed to a `List<? extends XTree>` parameter
>>  - Simplify inheritThrowsDocumentation
>>  - Reuse more specific variable
>>  - Merge branch 'master' into 8287333
>>  - Incremental update
>>    
>>    - Renames local variables and method parameters
>>    - Improves comments
>>    - Removes debug leftovers
>>  - Update top-level doc comment
>>  - ... and 25 more: https://git.openjdk.java.net/jdk/compare/f1dd559e...9c91efb0
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java line 281:
> 
>> 279:      * @param name            the name of the parameter.  We can't rely on
>> 280:      *                        the name in the param tag because we might be
>> 281:      *                        inheriting documentation.
> 
> This is useful info you are deleting :-(

It might be better if we agreed (to be discussed and decided separately, of course) on commenting only the stuff that requires comments. Not repetitive stuff whose meaning is very clear, and commenting which would be boring, useless and would add bulk. Otherwise, we might set up jdk.javadoc for more _comment skew_, which it  already has more than its fair share of.

Take this for example:

    @param writer          the taglet writer for output writing

What else would a method use such a parameter for? If we ever find an alternative use for a taglet writer, not only would I accept comments, I might ask for them.

Or this:

    @param kind            the kind of param tag

I cannot imagine any other description for such a method parameter. (Being pedantic, note that the comment doesn't explain which parameter that kind refers to: code readers somehow guess correctly.)

Not a requirement, bible or anything, but something you might want to have a look at: Chapter 4: Comments in Robert Cecil Martin's "Clean Code: A Handbook of Agile Software Craftsmanship" (2008).

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 56:
> 
>> 54: 
>> 55: /**
>> 56:  * A taglet that processes {@link ThrowsTree}, which represents tags like
> 
> rephrase without "like"

Fixed in 195f093ec55.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 112:
> 
>> 110:         Content result = writer.getOutputInstance();
>> 111:         Set<String> alreadyDocumented = new HashSet<>();
>> 112:         result.add(throwsTagsOutput(tagsMap, writer, alreadyDocumented, typeSubstitutions, true));
> 
> I presume `throwsTagsOutput` does not include the header...?

Do you mean "Throws:"? If so, then it does:

    if (alreadyDocumented.isEmpty()) {
        result.add(writer.getThrowsHeader());
    }

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java line 552:
> 
>> 550:     public ReferenceTree getExceptionName(ThrowsTree tt) {
>> 551:         return tt.getExceptionName();
>> 552:     }
> 
> Is this method worth it?

Maybe not. I left it there because of the similar `Utils.getParameterName` method, which is a tad bit more complicated:

    public String getParameterName(ParamTree p) {
        return p.getName().getName().toString();
    }

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

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