sample javadoc output for records and sealed types.
Brian Goetz
brian.goetz at oracle.com
Fri Oct 11 15:43:59 UTC 2019
I think it would be good if the javadoc always said “final” for records, regardless of what was in the source.
> On Oct 11, 2019, at 11:37 AM, Chris Hegarty <chris.hegarty at oracle.com> wrote:
>
> Jon,
>
> The javadoc looks great.
>
> I’m sure that this has come up already, but I cannot find it, so I’ll ask here.
>
> Should the javadoc include the fact that a record class is `final`? Or is that implied by the fact that it is a record?
>
> The reason I ask is that one can write `public final record R {}`. Will the javadoc for `R` show final? If so, then it could be a little confusing that the docs for some records may show final and others not. Maybe it just needs to be consistent one way or another. ( I found myself drawn to this question by the obvious presence of the public constructor )
>
> -Chris.
>
>> On 11 Oct 2019, at 01:00, Jonathan Gibbons <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>>
>> I've posted the javadoc output from some small examples of records and sealed types.
>>
>> Three of the examples, Point, BinaryNode and Holder, were suggested by Brian as
>> commonly used examples. The last example, Coords, declares a sealed type with
>> two different records as subtypes, just to show how the features can be used together.
>>
>> You can find the output here:
>>
>> http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-no-link/ <http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-no-link/>
>>
>> This is output from a "simple" run of javadoc, that does not link to JDK documentation.
>> In this version, references into java.base etc show up as unlinked monospaced text.
>>
>> http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-with-link/ <http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-with-link/>
>>
>> This is the output from a similar run of javadoc (same examples), but this time the
>> -linkoffline option was used so that references into java.base are linked as you would expect.
>>
>>
>> In both cases, I also used the "-linksource" option, so that you can also see the original
>> source file. Look for the link in the declaration of the type name near the top of each page.
>> For example, click on "Foo" where you see "public record Foo", etc.
>>
>> You can also see the raw source files here:
>> http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/src/ <http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/src/>
>> ------
>>
>> Discussion:
>>
>> Currently, the generated documentation consistently uses the full phrase "record components"
>> when referencing record components. This means that some of the generated text feels a
>> little clunky. I see that in some of the hard-written doc comments (e.g. on java.lang.Record)
>> the phrase is shortened to just "component" when the context is obvious. Do we want to do
>> the same here? Are there any guidelines on the terminology?
>>
>> Currently, following established historical precedent, records appear in their own group
>> on the package page, alongside individual groups for classes, interfaces, enums, exceptions,
>> errors and annotation types. For example, look at the docs for any recent version of java.lang:
>> https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/package-summary.html <https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/package-summary.html>
>> It may be that 7 (!!) groups is a few too many, and that maybe we should reorganize these pages
>> a bit, perhaps moving towards a tabbed table, of the sort we use on other pages. But whether
>> or not we do anything is out of scope for this project, and should be handled separately, as a
>> distinct enhancement for javadoc.
>>
>> -- Jon
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/amber-spec-experts/attachments/20191011/fe5aa4fb/attachment.html>
More information about the amber-spec-experts
mailing list