sample javadoc output for records and sealed types.

[Jonathan Gibbons]

Noted.   But I also note we suppress always-on modifiers for other 
elements :-)  So I guess we choose on a case-by-case basis.

FWIW, javadoc is driven by the Language Model (javax.lang.model) API, 
and not what is in the source code.

-- Jon

On 10/11/19 8:43 AM, Brian Goetz wrote:
> 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 
>> <mailto: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:
>>>
>>>  1. 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.
>>>
>>>  2. 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/
>>>
>>> ------
>>>
>>> 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
>>> 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/0b711124/attachment-0001.html>