JDK-8225055 : Javadoc for records
  • Type: Sub-task
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2019-05-30
  • Updated: 2019-12-13
  • Resolved: 2019-12-04
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 14
14 b27Fixed
Related Reports
Blocks :  
Blocks :  
Description
For records: 
    use correct "keyword" for type declaration
    `@param` on class (to document components)
    generation of Javadoc for mandated members: constructor, accessors, equals, hashCode etc also private field (for when `-private` is used)
        allow for user overrides
        ensure mandated members are indexed

For sealed types: 
    generate `sealed` and `non-sealed` as appropriate
    generating ���permitted subtypes��� section

For all types:
    if the supertype is sealed, and this type is unsealed, show `non-sealed`

For both:
    update the Class-Use pages
    update doclint to check @param on record types

Test cases:
    for sealed types, ensure implicit permitted subtypes are handled correctly (i.e. in a timely manner for javadoc)
    good @params, 
    bad @params: missing, wrong name, duplicate names
    explicitly-defined accessor methods for components and default constructor
    {@inheritDoc} in explicitly-defined accessor methods for components and default constructor

Comments
URL: https://hg.openjdk.java.net/jdk/jdk/rev/8e76f81d057a User: vromero Date: 2019-12-04 21:06:04 +0000
04-12-2019

yes in the case in which the user defines an accessor with no javadoc, we should generate the default text. And yes for sealed types there are no special javadoc tags to test
24-06-2019

For sealed types, there are no special javadoc tags to test; all the testing with be about weird shapes of positive test cases of different hierarchies of sealed and unsealed types, making sure they all get correct documentation generated in the signature part of the page.
24-06-2019

Test case and design question: user-defined access method with no comment: should we use the default text
24-06-2019

Records: we will "overload" the @param tag to reuse it for record components. The javadoc for mandated members can refer to the previously defined record components. For example if we have: record R(int a, int b); we could generate a header for that class like: /** R @param a javadoc comment for "a" @param b javadoc comment for "b" */ and then the javadoc for accessor a() could for example say: ```Retrieves the value of the <a href="#a">a</a> component``` similar for fields, constructor parameters, etc. the user could decide to declare explicitly a mandated member in that case, if the user doesn't define the javadoc, then we show the predefined one. If the defines the javadoc, then that one will be the javadoc shown. Description of possible test cases, in addition to the ones already mentioned: - user defined javadoc linking to incorrect record parameter - user defined javadoc with incorrect, or incomplete, permitted subtypes
24-06-2019

For javadoc (as compared to javac) I'n not so interested in cases that will fail at the language level, such as the "same name" example of a bad record. It's more interesting to imagine bad javadoc, e.g. where the collection of @param tags does not include duplicates, and the set matches the set of parameter names ... none missing, not extra
24-06-2019