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

[Kevin Rushforth]

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.

I ran javadoc with this patch to generate the JavaFX docs, and it all looks good. I verified that the synthesized `@see`, `@param`, and `@return`  are now all consistently added. The name of the property is now consistently in `<code></code>` style, too.

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

Marked as reviewed by kcr (Author).

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