changeset 23137:209daac13c8b

8035878: javadoc tool documentation should be using {@code ..} specifier Reviewed-by: jjg Contributed-by: neil.toda@oracle.com
author jjg
date Mon, 03 Mar 2014 15:24:31 -0800
parents aa8958a4c8f4
children 497fb20a5754
files langtools/src/share/classes/com/sun/javadoc/AnnotationValue.java langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java langtools/src/share/classes/com/sun/javadoc/ParamTag.java langtools/src/share/classes/com/sun/javadoc/ParameterizedType.java langtools/src/share/classes/com/sun/javadoc/RootDoc.java langtools/src/share/classes/com/sun/javadoc/SeeTag.java langtools/src/share/classes/com/sun/javadoc/Tag.java langtools/src/share/classes/com/sun/javadoc/ThrowsTag.java langtools/src/share/classes/com/sun/javadoc/package-info.java
diffstat 9 files changed, 52 insertions(+), 52 deletions(-) [+]
line wrap: on
line diff
--- a/langtools/src/share/classes/com/sun/javadoc/AnnotationValue.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/AnnotationValue.java	Mon Mar 03 15:24:31 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,11 +38,11 @@
      * Returns the value.
      * The type of the returned object is one of the following:
      * <ul><li> a wrapper class for a primitive type
-     *     <li> <code>String</code>
-     *     <li> <code>Type</code> (representing a class literal)
-     *     <li> <code>FieldDoc</code> (representing an enum constant)
-     *     <li> <code>AnnotationDesc</code>
-     *     <li> <code>AnnotationValue[]</code>
+     *     <li> {@code String}
+     *     <li> {@code Type} (representing a class literal)
+     *     <li> {@code FieldDoc} (representing an enum constant)
+     *     <li> {@code AnnotationDesc}
+     *     <li> {@code AnnotationValue[]}
      * </ul>
      *
      * @return the value.
--- a/langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java	Mon Mar 03 15:24:31 2014 -0800
@@ -103,8 +103,8 @@
     /**
      * Return the throws tags in this method.
      *
-     * @return an array of ThrowTag containing all {@code &#64;exception}
-     * and {@code &#64;throws} tags.
+     * @return an array of ThrowTag containing all {@code @exception}
+     * and {@code @throws} tags.
      */
     ThrowsTag[] throwsTags();
 
@@ -112,7 +112,7 @@
      * Return the param tags in this method, excluding the type
      * parameter tags.
      *
-     * @return an array of ParamTag containing all {@code &#64;param} tags
+     * @return an array of ParamTag containing all {@code @param} tags
      * corresponding to the parameters of this method.
      */
     ParamTag[] paramTags();
@@ -120,7 +120,7 @@
     /**
      * Return the type parameter tags in this method.
      *
-     * @return an array of ParamTag containing all {@code &#64;param} tags
+     * @return an array of ParamTag containing all {@code @param} tags
      * corresponding to the type parameters of this method.
      * @since 1.5
      */
--- a/langtools/src/share/classes/com/sun/javadoc/ParamTag.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/ParamTag.java	Mon Mar 03 15:24:31 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,7 +38,7 @@
 
     /**
      * Return the name of the parameter or type parameter
-     * associated with this <code>ParamTag</code>.
+     * associated with this {@code ParamTag}.
      * The angle brackets delimiting a type parameter are not part of
      * its name.
      *
@@ -48,18 +48,18 @@
 
     /**
      * Return the parameter comment
-     * associated with this <code>ParamTag</code>.
+     * associated with this {@code ParamTag}.
      *
      * @return the parameter comment.
      */
     String parameterComment();
 
     /**
-     * Return true if this <code>ParamTag</code> corresponds to a type
+     * Return true if this {@code ParamTag} corresponds to a type
      * parameter.  Return false if it corresponds to an ordinary parameter
      * of a method or constructor.
      *
-     * @return true if this <code>ParamTag</code> corresponds to a type
+     * @return true if this {@code ParamTag} corresponds to a type
      * parameter.
      * @since 1.5
      */
--- a/langtools/src/share/classes/com/sun/javadoc/ParameterizedType.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/ParameterizedType.java	Mon Mar 03 15:24:31 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -97,10 +97,10 @@
      * Return null is this is a top-level type.
      *
      * <p> For example, the containing type of
-     * {@code AnInterface.Nested<Number>} is the <code>ClassDoc</code>
+     * {@code AnInterface.Nested<Number>} is the {@code ClassDoc}
      * representing {@code AnInterface}, and the containing type of
      * {@code Outer<String>.Inner<Number>} is the
-     * <code>ParameterizedType</code> representing {@code Outer<String>}.
+     * {@code ParameterizedType} representing {@code Outer<String>}.
      *
      * @return the type that contains this type as a member.
      */
--- a/langtools/src/share/classes/com/sun/javadoc/RootDoc.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/RootDoc.java	Mon Mar 03 15:24:31 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -60,7 +60,7 @@
      * Return the packages
      * <a href="package-summary.html#included">specified</a>
      * on the command line.
-     * If <code>-subpackages</code> and <code>-exclude</code> options
+     * If {@code -subpackages} and {@code -exclude} options
      * are used, return all the non-excluded packages.
      *
      * @return packages specified on the command line.
--- a/langtools/src/share/classes/com/sun/javadoc/SeeTag.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/SeeTag.java	Mon Mar 03 15:24:31 2014 -0800
@@ -31,7 +31,7 @@
  * plain text.  (The plain text might be a reference
  * to something not online, such as a printed book, or be a hard-coded
  * HTML link.)  The reference can either be inline with the comment,
- * using {@code &#123;@link}}, or a separate block comment,
+ * using {@code {@link}}, or a separate block comment,
  * using {@code @see}.
  * Method {@code name()} returns "@link" (no curly braces) or
  * "@see", depending on the tag.
@@ -86,10 +86,10 @@
      * return "java.lang.String".
      * For "{@code @see java.lang}", return "java.lang".
      * Return null if {@code @see} references a non-element, such as
-     * {@code @see &lt;a href="java.sun.com"&gt;}.
+     * {@code @see <a href="java.sun.com">}.
      *
      * @return null if {@code @see} references a non-element, such as
-     * {@code @see &lt;a href="java.sun.com"&gt;}.
+     * {@code @see <a href="java.sun.com">}.
      */
     String referencedClassName();
 
--- a/langtools/src/share/classes/com/sun/javadoc/Tag.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/Tag.java	Mon Mar 03 15:24:31 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -33,7 +33,7 @@
  * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")
  * and tag text (e.g. "1.2").  Tags with structure or which require
  * special processing are handled by subclasses such as ParamTag
- * (for @param), SeeTag (for @see and {&#064;link}), and ThrowsTag
+ * (for @param), SeeTag (for @see and {@link}), and ThrowsTag
  * (for @throws).
  *
  * @author Robert Field
@@ -50,10 +50,10 @@
     /**
      * Return the name of this tag.  The name is the string
      * starting with "@" that is used in a doc comment, such as
-     * <code>@return</code>.  For inline tags, such as
-     * <code>{&#064;link}</code>, the curly brackets
+     * {@code @return}.  For inline tags, such as
+     * {@code {@link}}, the curly brackets
      * are not part of the name, so in this example the name
-     * would be simply <code>@link</code>.
+     * would be simply {@code @link}.
      *
      * @return the name of this tag
      */
@@ -69,7 +69,7 @@
     /**
      * Return the kind of this tag.
      * For most tags,
-     * <code>kind()&nbsp;==&nbsp;name()</code>;
+     * {@code kind() == name()};
      * the following table lists those cases where there is more
      * than one tag of a given kind:
      *
@@ -101,27 +101,27 @@
     String toString();
 
     /**
-     * For a documentation comment with embedded <code>{&#064;link}</code>
-     * tags, return an array of <code>Tag</code> objects.  The entire
+     * For a documentation comment with embedded {@code {@link}}
+     * tags, return an array of {@code Tag} objects.  The entire
      * doc comment is broken down into strings separated by
-     * <code>{&#064;link}</code> tags, where each successive element
+     * {@code {@link}} tags, where each successive element
      * of the array represents either a string or
-     * <code>{&#064;link}</code> tag, in order, from start to end.
-     * Each string is represented by a <code>Tag</code> object of
+     * {@code {@link}} tag, in order, from start to end.
+     * Each string is represented by a {@code Tag} object of
      * name "Text", where {@link #text()} returns the string.  Each
-     * <code>{&#064;link}</code> tag is represented by a
+     * {@code {@link}} tag is represented by a
      * {@link SeeTag} of name "@link" and kind "@see".
      * For example, given the following comment
      * tag:
      * <p>
-     *  <code>This is a {&#064;link Doc commentlabel} example.</code>
+     *  {@code This is a {@link Doc commentlabel} example.}
      * <p>
      * return an array of Tag objects:
      * <ul>
      *    <li> tags[0] is a {@link Tag} with name "Text" and text consisting
      *         of "This is a "
      *    <li> tags[1] is a {@link SeeTag} with name "@link", referenced
-     *         class <code>Doc</code> and label "commentlabel"
+     *         class {@code Doc} and label "commentlabel"
      *    <li> tags[2] is a {@link Tag} with name "Text" and text consisting
      *         of " example."
      * </ul>
--- a/langtools/src/share/classes/com/sun/javadoc/ThrowsTag.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/ThrowsTag.java	Mon Mar 03 15:24:31 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,7 +39,7 @@
 
     /**
      * Return the name of the exception
-     * associated with this <code>ThrowsTag</code>.
+     * associated with this {@code ThrowsTag}.
      *
      * @return name of the exception.
      */
@@ -47,30 +47,30 @@
 
     /**
      * Return the exception comment
-     * associated with this <code>ThrowsTag</code>.
+     * associated with this {@code ThrowsTag}.
      *
      * @return exception comment.
      */
     String exceptionComment();
 
     /**
-     * Return a <code>ClassDoc</code> that represents the exception.
+     * Return a {@code ClassDoc} that represents the exception.
      * If the type of the exception is a type variable, return the
-     * <code>ClassDoc</code> of its erasure.
+     * {@code ClassDoc} of its erasure.
      *
      * <p> <i>This method cannot accommodate certain generic type
-     * constructs.  The <code>exceptionType</code> method
+     * constructs.  The {@code exceptionType} method
      * should be used instead.</i>
      *
-     * @return <code>ClassDoc</code> that represents the exception.
+     * @return {@code ClassDoc} that represents the exception.
      * @see #exceptionType
      */
     ClassDoc exception();
 
     /**
      * Return the type of the exception
-     * associated with this <code>ThrowsTag</code>.
-     * This may be a <code>ClassDoc</code> or a <code>TypeVariable</code>.
+     * associated with this {@code ThrowsTag}.
+     * This may be a {@code ClassDoc} or a {@code TypeVariable}.
      *
      * @return the type of the exception.
      * @since 1.5
--- a/langtools/src/share/classes/com/sun/javadoc/package-info.java	Mon Mar 03 15:10:01 2014 -0800
+++ b/langtools/src/share/classes/com/sun/javadoc/package-info.java	Mon Mar 03 15:24:31 2014 -0800
@@ -53,8 +53,8 @@
 When calling javadoc, you pass in package names and source file names --
 these are called the <em>specified</em> packages and classes.
 You also pass in Javadoc options; the <em>access control</em> Javadoc options
-(<code>-public</code>, <code>-protected</code>, <code>-package</code>,
-and <code>-private</code>) filter program elements, producing a
+({@code -public}, {@code -protected}, {@code -package},
+and {@code -private}) filter program elements, producing a
 result set, called the <em>included</em> set, or "documented" set.
 (The unfiltered set is also available through
 {@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.)
@@ -78,15 +78,15 @@
 
 <a name="qualified"></a>
 A <em>qualified</em> class or interface name is one that has its package
-name prepended to it, such as <code>java.lang.String</code>.  A non-qualified
-name has no package name, such as <code>String</code>.
+name prepended to it, such as {@code java.lang.String}.  A non-qualified
+name has no package name, such as {@code String}.
 <p>
 
 <a name="example"></a>
 <h3>Example</h3>
 
 The following is an example doclet that
-displays information in the <code>@param</code> tags of the processed
+displays information in the {@code @param} tags of the processed
 classes:
 <pre>
 import com.sun.javadoc.*;
@@ -124,7 +124,7 @@
 superinterface of {@link com.sun.javadoc.MethodDoc} and
 {@link com.sun.javadoc.ConstructorDoc},
 and {@link com.sun.javadoc.ParamTag} holds information
-from "<code>@param</code>" tags.
+from "{@code @param}" tags.
 <p>
 This doclet when invoked with a command line like:
 <pre>