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 <[email protected]> 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 <[email protected] >> <mailto:[email protected]>> 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 >> >> >
