-
Notifications
You must be signed in to change notification settings - Fork 5.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
JDK-8305593: Add @spec tags in java.desktop #13360
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -222,7 +222,8 @@ public final class BaselineTIFFTagSet extends TIFFTagSet { | |
* A value to be used with the "Compression" tag. | ||
* | ||
* @see #TAG_COMPRESSION | ||
* @see <a href="https://tools.ietf.org/html/rfc1951">DEFLATE specification</a> | ||
* @spec https://www.rfc-editor.org/info/rfc1951 | ||
* RFC 1951: DEFLATE Compressed Data Format Specification version 1.3 | ||
*/ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. OK. So why are you preferring this rfc-editor.org site ? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Because we were strongly recommended to do so, in an earlier round of review. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I have no idea who that person is with the strong opinions, and hence no idea of his standing to assert the opinion. |
||
public static final int COMPRESSION_DEFLATE = 32946; | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The javadoc above references ietf.org. This tag references rfc-editor.org. It seems odd to use two different URLs
in the same method specification for the same RFC. I would have thought the ietf one better to use .. although it should be updated to https
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This work is primarily about adding
@spec
tags, in a semi-automated fashion, using a custom utility that scans comments in the public API, looking forhref
s to "well-known" sites hosting external specifications. While "mostly automated", I did manually cleanup the references by line-wrapping as appropriate.It is out of scope at this time to cleanup up the underlying
href
s, although we should look at cleaning up those links later, identifying the latest/preferred URL for the appropriate version of the spec document, which may or may not be the latest overall version of the spec. (For example, the client docs reference HTML 3.2, and should not reference anything more recent.). This cleanup can be done later and needs to be done in conjunction with the relevant teams, and probably not as a semi-automated update. Such cleanup should be somewhat easier once we have tagged the affected comments with the relevant@spec
tags.I note that once we have completed the addition of the
@spec
tags, we will, re-enable the new "External Specifications" page, which cross-references where each individual external specification is mentioned in the overall API documentation.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry, but no matter how many times I try, it seems wrong to even for some short amount of time to have @SPEC point to one place and the javadoc point to another. They should always be consistent.
If it is out of scope to update the javadoc, then the new spec tag should just match the existing javadoc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For the
rfc-editor.org
that's going to be hard, insofar as there are strong opinions (voiced in an earlier round of review) about using references to the old sites.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see just 18 references matching
href=....ietf.org
so I guess I can manually update those for you.