sample javadoc output for records and sealed types.

[Maurizio Cimadamore]

I think the output looks very clean. On the 'sealed' part I have no 
objectctions.

On records, what you did looks, again, very clean. The only comment I 
have there is that it "feels" like something is missing in the summary 
section... e.g. for some reason I would expect a "record components 
summary" there. I noted that you lifted the components to the toplevel 
doc, but I wondering if that's the right move.

If we had specific entries for components, then we could also link e.g. 
the accessor to the component summary which would be, I think, cool. In 
other words, the treatment of JavaFX comes to mind:

https://docs.oracle.com/javase/9/docs/api/javafx/scene/chart/Chart.html

Also, there's a precedent: enums:

https://docs.oracle.com/javase/9/docs/api/java/lang/annotation/ElementType.html

Here, again, we have a summary section for all the constants.

Don't get me wrong, what you have is good enough for day 1, I'm mostly 
trying to see how much rope we can pull.

Maurizio


On 11/10/2019 01:00, Jonathan Gibbons 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/b4d8ca17/attachment.html>