[clarification]: copyedit javadoc before release

[gavinking]

Specification

javadoc

I need clarification on ...

formatting and style.

Additional information

Before release, I think we need to go over the javadoc completely looking for minor things like the following:

• Jagged line-lengths and lines which overflow the screen. Recent version of IntelliJ do a much better job of displaying javadoc, and of course in some cases it's very hard to make the line lengths consistent due to the use of {@ link} but even so, we can do better.
• Use of <code> instead of {@code}
• Use of informal language which addresses the user directly, e.g. "If you define a method...".

I would also prefer to see the work "keyset" go away if possible.

[njr-11]

• Jagged line-lengths and lines which overflow the screen. Recent version of IntelliJ do a much better job of displaying javadoc, and of course in some cases it's very hard to make the line lengths consistent due to the use of {@ link} but even so, we can do better.

• Use of <code> instead of {@code}

I'm fine with this, but would consider it low priority because it can be adjusted at any point and is not a breaking change.
What is a good guideline for line length? If everyone has the same number in mind, it will help ensure it gets written in a compliant manner the first time.

• Use of informal language which addresses the user directly, e.g. "If you define a method..."

The guideline that I would use here is that this sort of language is appropriate in JavaDoc that is meant for the end user, but it does not belong in the specification, which tends to be targeted toward implementors.

I would also prefer to see the word "keyset" go away if possible.

This makes sense if the pull that switches to CursoredPage goes in because we will no longer have a class name with keyset in it.

[gavinking]

This is was mostly solved by #528 and #525.

[KyleAure]

Closing issue as completed for the Jakarta Data 1.0 milestone