8035878: javadoc tool documentation should be using {@code ..} specifier
Reviewed-by: jjg
Contributed-by: neil.toda@oracle.com
--- 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 @exception}
- * and {@code @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 @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 @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 {@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 <a href="java.sun.com">}.
+ * {@code @see <a href="java.sun.com">}.
*
* @return null if {@code @see} references a non-element, such as
- * {@code @see <a href="java.sun.com">}.
+ * {@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 {@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>{@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() == 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>{@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>{@link}</code> tags, where each successive element
+ * {@code {@link}} tags, where each successive element
* of the array represents either a string or
- * <code>{@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>{@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 {@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>