RFR: JDK-8270195: Add missing links between methods of JavaFX properties

[Hannes Wallnöfer]

On Thu, 12 Aug 2021 17:38:14 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a medium-size update to the support for JavaFX properties in the Standard Doclet.
> 
> A JavaFX property is typically defined by a group of up to 4 elements:
> * an optional field, which is typically private
> * a no-args property method, whose name ends in `Property` and which returns an appropriate property object
> * an optional getter method which can get the value of the property
> * an optional setter method which can set the value of the property
> 
> Either the field (if present) or the property method (but not both) should have a comment describing the property. The rest should generally _not_have comments: comments will be automatically generated.
> 
> This change is primarily to improve the generation of the comments. `@see` links are generated between the methods for a property. In addition, improvements are made to the handling of `@return` ... adding it as needed, and removing it when not (the latter occurs when generating the docs for the property itself, using the info in the property method.)
> 
> There is some amount of cleanup to the implementation, most notably moving (and rewriting) the code to generate comments for property methods from `MemberSummaryBuilder` to `CommentUtils`,which is where most other synthesized comments are generated. However, the goal has also been to not unduly change the spirit and spec of the original code.
> 
> A new combo test for JavaFX properties is provided, that creates different instances of a class, containing different property-related methods with and without comments. Basic properties of the output are then verified for each property method: the description, any parameter info, any return info, and any links to other related methods.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java line 528:

> 526:      * @return a content tree for the text
> 527:      */
> 528:     public List<? extends DocTree> getComment(String key, Object o0, Object o1, Object o2) {

What is the purpose of this rather complex method to format a text resource? It seems like it is arguments `o1` and `o2` are never used. Couldn't this be implemented simply using `MessageFormat` as it used to be?

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

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