Skip to content
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.

Sign up for GitHub

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

Jump to bottom

JDK-8305593: Add @spec tags in java.desktop #13360

Closed
wants to merge 3 commits into from
Closed

JDK-8305593: Add @spec tags in java.desktop #13360

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
374a088
JDK-8305593: Add @spec tags in java.desktop
jonathan-gibbons Apr 5, 2023
abe6fa1
Merge remote-tracking branch 'upstream/master' into 8305593.at-spec-j…
jonathan-gibbons May 31, 2023
fcccc85
Update narrative references to use `rfc-editor.org` instead of (varia…
jonathan-gibbons May 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/java.desktop/share/classes/java/awt/Desktop.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -569,7 +569,7 @@ public void mail() throws IOException {
* <p> A {@code mailto:} URI can specify message fields
* including <i>"to"</i>, <i>"cc"</i>, <i>"subject"</i>,
* <i>"body"</i>, etc. See <a
* href="http://www.ietf.org/rfc/rfc2368.txt">The mailto URL
* href="https://www.rfc-editor.org/info/rfc2368">The mailto URL
* scheme (RFC 2368)</a> for the {@code mailto:} URI specification
* details.
*
Expand All @@ -587,6 +587,8 @@ public void mail() throws IOException {
* {@code AWTPermission("showWindowWithoutWarningBanner")}
* permission, or the calling thread is not allowed to create a
* subprocess
* @spec https://www.rfc-editor.org/info/rfc2368
* RFC 2368: The mailto URL scheme
Copy link
Contributor

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

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Apr 11, 2023 •
edited
Loading

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 for hrefs 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 hrefs, 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.

Copy link
Contributor

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.

Copy link
Contributor Author

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.

Copy link
Contributor Author

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.

$ grep -r 'href=[^ ]*ietf.org' open/src/java.desktop
open/src/java.desktop/share/classes/sun/awt/image/PNGImageDecoder.java:    See <a href=http://www.ietf.org/rfc/rfc2083.txt>RFC2083</a> for details. */
open/src/java.desktop/share/classes/java/awt/Desktop.java:     * href="http://www.ietf.org/rfc/rfc2368.txt">The mailto URL
open/src/java.desktop/share/classes/java/awt/peer/DesktopPeer.java:     *        <a href="http://www.ietf.org/rfc/rfc2368.txt">RFC2368: The mailto
open/src/java.desktop/share/classes/javax/print/attribute/standard/Compression.java:     * <a href="http://www.ietf.org/rfc/rfc1952.txt">RFC 1952</a>.
open/src/java.desktop/share/classes/javax/print/attribute/standard/MediaSizeName.java: * <a href="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911</a>
open/src/java.desktop/share/classes/javax/print/attribute/standard/Fidelity.java: * <a href="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911</a> Section 15.1 for a
open/src/java.desktop/share/classes/javax/print/attribute/standard/package-info.java: * <a href="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911</a> for more
open/src/java.desktop/share/classes/javax/print/DocFlavor.java: *   <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a> and
open/src/java.desktop/share/classes/javax/print/DocFlavor.java: *   <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>) that specifies
open/src/java.desktop/share/classes/javax/print/DocFlavor.java: * <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>, which says the
open/src/java.desktop/share/classes/javax/print/DocFlavor.java:     * <a href="http://www.ietf.org/rfc/rfc2278.txt">
open/src/java.desktop/share/classes/javax/print/package-info.java: * <a href="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911 Internet Printing
open/src/java.desktop/share/classes/javax/print/MimeType.java: * <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a> and
open/src/java.desktop/share/classes/javax/print/MimeType.java: * <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>. A MIME type
open/src/java.desktop/share/classes/javax/imageio/plugins/tiff/BaselineTIFFTagSet.java:     * @see <a href="https://tools.ietf.org/html/rfc1951">DEFLATE specification</a>
open/src/java.desktop/share/classes/javax/imageio/plugins/tiff/FaxTIFFTagSet.java: * <a href="https://tools.ietf.org/html/rfc2306.html">TIFF-F</a> (RFC 2036) file.
open/src/java.desktop/share/classes/javax/imageio/metadata/doc-files/tiff_metadata.html:<td><a href="https://tools.ietf.org/html/rfc1950">
open/src/java.desktop/share/classes/javax/imageio/metadata/doc-files/tiff_metadata.html:<a href="https://tools.ietf.org/html/rfc1951">
$ grep -r 'href=[^ ]*ietf.org' open/src/java.desktop | wc -l
      18

* @see java.net.URI
* @see java.awt.AWTPermission
*/
Expand Down
4 changes: 2 additions & 2 deletions src/java.desktop/share/classes/java/awt/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,10 @@
* <ul>
* <li><a href="doc-files/FocusSpec.html">The AWT Focus Subsystem</a>
* <li><a href="doc-files/Modality.html">The AWT Modality</a>
* <li><a href="{@docRoot}/../specs/AWT_Native_Interface.html">
* The Java AWT Native Interface (JAWT)</a>
* </ul>
*
* @spec AWT_Native_Interface.html
* The Java AWT Native Interface Specification and Guide
* @since 1.0
*/
package java.awt;
5 changes: 4 additions & 1 deletion src/java.desktop/share/classes/java/awt/peer/DesktopPeer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,13 @@ public interface DesktopPeer {
*
* @param mailtoURL represents a mailto URL with specified values of the message.
* The syntax of mailto URL is defined by
* <a href="http://www.ietf.org/rfc/rfc2368.txt">RFC2368: The mailto
* <a href="https://www.rfc-editor.org/info/rfc2368">RFC2368: The mailto
* URL scheme</a>
* @throws IOException If the user default mail client is not found,
* or it fails to be launched.
*
* @spec https://www.rfc-editor.org/info/rfc2368
* RFC 2368: The mailto URL scheme
*/
void mail(URI mailtoURL) throws IOException;

Expand Down
4 changes: 2 additions & 2 deletions src/java.desktop/share/classes/javax/imageio/metadata/doc-files/tiff_metadata.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -565,9 +565,9 @@ <h3><a id="Compression">Compression</a></h3>
<th scope="row">8</th>
<td>Deflate</td>
<td>"Zip-in-TIFF" compression (see note following this table)</td>
<td><a href="https://tools.ietf.org/html/rfc1950">
<td><a href="https://www.rfc-editor.org/info/rfc1950">
ZLIB Compressed Data Format Specification</a>,
<a href="https://tools.ietf.org/html/rfc1951">
<a href="https://www.rfc-editor.org/info/rfc1951">
DEFLATE Compressed Data Format Specification</a></td>
</tr>
<tr>
Expand Down
3 changes: 2 additions & 1 deletion src/java.desktop/share/classes/javax/imageio/plugins/tiff/BaselineTIFFTagSet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK. So why are you preferring this rfc-editor.org site ?
Seems we should get that cleared up before I look further

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.

Copy link
Contributor

Choose a reason for hiding this comment

The 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.
So I'd be reluctant to follow his suggestion without more info.
But they still should be the same.

public static final int COMPRESSION_DEFLATE = 32946;

Expand Down
4 changes: 3 additions & 1 deletion src/java.desktop/share/classes/javax/imageio/plugins/tiff/FaxTIFFTagSet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,10 @@

/**
* A class representing the extra tags found in a
* <a href="https://tools.ietf.org/html/rfc2306.html">TIFF-F</a> (RFC 2036) file.
* <a href="https://www.rfc-editor.org/info/rfc2306">TIFF-F</a> (RFC 2036) file.
*
* @spec https://www.rfc-editor.org/info/rfc2306
* RFC 2306: Tag Image File Format (TIFF) - F Profile for Facsimile
* @since 9
*/
public final class FaxTIFFTagSet extends TIFFTagSet {
Expand Down
12 changes: 9 additions & 3 deletions src/java.desktop/share/classes/javax/print/DocFlavor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@
* <ul>
* <li><b>MIME type.</b> This is a Multipurpose Internet Mail Extensions
* (MIME) media type (as defined in
* <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a> and
* <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>) that specifies
* <a href="https://www.rfc-editor.org/info/rfc2045">RFC 2045</a> and
* <a href="https://www.rfc-editor.org/info/rfc2046">RFC 2046</a>) that specifies
* how the print data is to be interpreted. The charset of text data should be
* the IANA MIME-preferred name, or its canonical name if no preferred name is
* specified. Additionally a few historical names supported by earlier
Expand Down Expand Up @@ -383,6 +383,10 @@
* Print Service instance supports without having to load the representation
* classes, which may be problematic for limited-resource clients.
*
* @spec https://www.rfc-editor.org/info/rfc2045
* RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies
* @spec https://www.rfc-editor.org/info/rfc2046
* RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
* @author Alan Kaminsky
*/
public class DocFlavor implements Serializable, Cloneable {
Expand All @@ -396,13 +400,15 @@ public class DocFlavor implements Serializable, Cloneable {
/**
* A string representing the host operating system encoding. This will
* follow the conventions documented in
* <a href="http://www.ietf.org/rfc/rfc2278.txt">
* <a href="https://www.rfc-editor.org/info/rfc2278">
* <i>RFC&nbsp;2278:&nbsp;IANA Charset Registration Procedures</i></a>
* except where historical names are returned for compatibility with
* previous versions of the Java platform. The value returned from method is
* valid only for the VM which returns it, for use in a {@code DocFlavor}.
* This is the charset for all the "HOST" pre-defined {@code DocFlavors} in
* the executing VM.
* @spec https://www.rfc-editor.org/info/rfc2278
* RFC 2278: IANA Charset Registration Procedures
*/
@SuppressWarnings("removal")
public static final String hostEncoding =
Expand Down
8 changes: 6 additions & 2 deletions src/java.desktop/share/classes/javax/print/MimeType.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@
/**
* Class {@code MimeType} encapsulates a Multipurpose Internet Mail Extensions
* (MIME) media type as defined in
* <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a> and
* <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>. A MIME type
* <a href="https://www.rfc-editor.org/info/rfc2045">RFC 2045</a> and
* <a href="https://www.rfc-editor.org/info/rfc2046">RFC 2046</a>. A MIME type
* object is part of a {@link DocFlavor DocFlavor} object and specifies the
* format of the print data.
* <p>
Expand Down Expand Up @@ -74,6 +74,10 @@
* </ul>
*
* @author Alan Kaminsky
* @spec https://www.rfc-editor.org/info/rfc2045
* RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies
* @spec https://www.rfc-editor.org/info/rfc2046
* RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
*/
class MimeType implements Serializable, Cloneable {

Expand Down
4 changes: 3 additions & 1 deletion src/java.desktop/share/classes/javax/print/attribute/standard/Compression.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,9 @@ public class Compression extends EnumSyntax implements DocAttribute {

/**
* GNU zip compression technology described in
* <a href="http://www.ietf.org/rfc/rfc1952.txt">RFC 1952</a>.
* <a href="https://www.rfc-editor.org/info/rfc1952">RFC 1952</a>.
* @spec https://www.rfc-editor.org/info/rfc1952
* RFC 1952: GZIP file format specification version 4.3
*/
public static final Compression GZIP = new Compression(2);

Expand Down
5 changes: 4 additions & 1 deletion src/java.desktop/share/classes/javax/print/attribute/standard/Fidelity.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,11 @@
* name returned by {@code getName()} is the IPP attribute name. The
* enumeration's integer value is the IPP enum value. The {@code toString()}
* method returns the IPP string representation of the attribute value. See
* <a href="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911</a> Section 15.1 for a
* <a href="https://www.rfc-editor.org/info/rfc2911">RFC 2911</a> Section 15.1 for a
* fuller description of the IPP fidelity attribute.
*
* @spec https://www.rfc-editor.org/info/rfc2911
* RFC 2911: Internet Printing Protocol/1.1: Model and Semantics
*/
public final class Fidelity extends EnumSyntax
implements PrintJobAttribute, PrintRequestAttribute {
Expand Down
5 changes: 4 additions & 1 deletion src/java.desktop/share/classes/javax/print/attribute/standard/MediaSizeName.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,10 @@
* <b>IPP Compatibility:</b> {@code MediaSizeName} is a representation class for
* values of the IPP "media" attribute which names media sizes. The names of the
* media sizes correspond to those in the IPP 1.1 RFC
* <a href="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911</a>
* <a href="https://www.rfc-editor.org/info/rfc2911">RFC 2911</a>
*
* @spec https://www.rfc-editor.org/info/rfc2911
* RFC 2911: Internet Printing Protocol/1.1: Model and Semantics
*/
public class MediaSizeName extends Media {

Expand Down
4 changes: 3 additions & 1 deletion src/java.desktop/share/classes/javax/print/attribute/standard/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@
* based on the Internet Printing Protocol (IPP) attributes as defined in the
* Internet RFC document, <i>RFC 2911 Internet Printing Protocol/1.1: Model and
* Semantics</i> dated September 2000. See
* <a href="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911</a> for more
* <a href="https://www.rfc-editor.org/info/rfc2911">RFC 2911</a> for more
* information. The descriptive text for each attribute class was taken largely
* from the above documents. The above authors' contribution to the API is
* gratefully acknowledged.
Expand Down Expand Up @@ -590,6 +590,8 @@
* later time. {@code IllegalArgumentException} and {@code NullPointerException}
* are examples of typical and acceptable run time exceptions for such cases.
*
* @spec https://www.rfc-editor.org/info/rfc2911
* RFC 2911: Internet Printing Protocol/1.1: Model and Semantics
* @since 1.4
*/
package javax.print.attribute.standard;
4 changes: 3 additions & 1 deletion src/java.desktop/share/classes/javax/print/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@
* {@code javax.print.attribute.standard} package enumerates all of the standard
* attributes supported by the API, most of which are implementations of
* attributes specified in the IETF Specification,
* <a href="http://www.ietf.org/rfc/rfc2911.txt">RFC 2911 Internet Printing
* <a href="https://www.rfc-editor.org/info/rfc2911">RFC 2911 Internet Printing
* Protocol, 1.1: Model and Semantics</a>, dated September 2000. The attributes
* specified in {@code javax.print.attribute.standard} include common
* capabilities, such as: resolution, copies, media sizes, job priority, and
Expand Down Expand Up @@ -127,6 +127,8 @@
* later time. {@code IllegalArgumentException} and {@code NullPointerException}
* are examples of typical and acceptable run time exceptions for such cases.
*
* @spec https://www.rfc-editor.org/info/rfc2911
* RFC 2911: Internet Printing Protocol/1.1: Model and Semantics
* @since 1.4
*/
package javax.print;
2 changes: 2 additions & 0 deletions src/java.desktop/share/classes/javax/swing/JEditorPane.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1615,6 +1615,8 @@ private void writeObject(ObjectOutputStream s) throws IOException {
* it set the client {@link #putClientProperty property} with this name
* to <code>Boolean.TRUE</code>.
*
* @spec https://www.w3.org/TR/CSS22
* Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification
* @since 1.5
*/
public static final String W3C_LENGTH_UNITS = "JEditorPane.w3cLengthUnits";
Expand Down
1 change: 1 addition & 0 deletions src/java.desktop/share/classes/javax/swing/text/html/CSS.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@
* unless noted, so that
* p { margin-top: 10% } will be treated as if no margin-top was specified.</b>
*
* @spec https://www.w3.org/TR/REC-CSS1 Cascading Style Sheets, level 1
* @author Timothy Prinzing
* @author Scott Violet
* @see StyleSheet
Expand Down
1 change: 1 addition & 0 deletions src/java.desktop/share/classes/javax/swing/text/html/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@
* which HTMLEditorKit is based.
* </ul>
*
* @spec https://www.w3.org/TR/REC-html32.html HTML 3.2 Reference Specification
* @since 1.2
* @serial exclude
*/
Expand Down
2 changes: 1 addition & 1 deletion src/java.desktop/share/classes/sun/awt/image/PNGImageDecoder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
import java.awt.Color;

/** PNG - Portable Network Graphics - image file reader.
See <a href=http://www.ietf.org/rfc/rfc2083.txt>RFC2083</a> for details. */
See <a href="https://www.rfc-editor.org/info/rfc2083">RFC2083</a> for details. */
public class PNGImageDecoder extends ImageDecoder
{
private static final int GRAY=0;
Expand Down