On Thu, 12 Aug 2021 17:38:14 GMT, Jonathan Gibbons <[email protected]> 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
