On Thu, 12 Aug 2021 17:38:14 GMT, Jonathan Gibbons <j...@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
