changeset 3231:e9b4d00dfb75

8035877: javadoc classes are missing @return and @param tags Reviewed-by: jjg Contributed-by: neil.toda@oracle.com
author jjg
date Mon, 03 Mar 2014 15:10:01 -0800
parents 96ebdbb37e6d
children 9280e0d9569d
files src/share/classes/com/sun/javadoc/ClassDoc.java src/share/classes/com/sun/javadoc/Doc.java src/share/classes/com/sun/javadoc/Doclet.java src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java src/share/classes/com/sun/javadoc/FieldDoc.java src/share/classes/com/sun/javadoc/MemberDoc.java src/share/classes/com/sun/javadoc/MethodDoc.java src/share/classes/com/sun/javadoc/PackageDoc.java src/share/classes/com/sun/javadoc/Parameter.java src/share/classes/com/sun/javadoc/ProgramElementDoc.java src/share/classes/com/sun/javadoc/SeeTag.java src/share/classes/com/sun/javadoc/SerialFieldTag.java src/share/classes/com/sun/javadoc/SourcePosition.java src/share/classes/com/sun/javadoc/Type.java src/share/classes/com/sun/javadoc/TypeVariable.java
diffstat 15 files changed, 225 insertions(+), 110 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/com/sun/javadoc/ClassDoc.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/ClassDoc.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2012, 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
@@ -46,28 +46,40 @@
     /**
      * Return true if this class is abstract.  Return true
      * for all interfaces.
+     *
+     * @return true if this class is abstract.  Return true
+     *         for all interfaces.
      */
     boolean isAbstract();
 
     /**
      * Return true if this class implements or interface extends
-     * <code>java.io.Serializable</code>.
+     * {@code java.io.Serializable}.
      *
-     * Since <code>java.io.Externalizable</code> extends
-     * <code>java.io.Serializable</code>,
+     * Since {@code java.io.Externalizable} extends
+     * {@code java.io.Serializable},
      * Externalizable objects are also Serializable.
+     *
+     * @return true if this class implements or interface extends
+     *         {@code java.io.Serializable}.
      */
     boolean isSerializable();
 
     /**
      * Return true if this class implements or interface extends
-     * <code>java.io.Externalizable</code>.
+     * {@code java.io.Externalizable}.
+     *
+     * @return true if this class implements or interface extends
+     *         {@code java.io.Externalizable}.
      */
     boolean isExternalizable();
 
     /**
      * Return true if this class can be used as a target type of a lambda expression
      * or method reference.
+     *
+     * @return true if this class can be used as a target type of a lambda expression
+     *         or method reference.
      */
     boolean isFunctionalInterface();
 
@@ -84,14 +96,14 @@
      * Return the Serializable fields of this class or interface.
      * <p>
      * Return either a list of default fields documented by
-     * <code>serial</code> tag<br>
-     * or return a single <code>FieldDoc</code> for
-     * <code>serialPersistentField</code> member.
-     * There should be a <code>serialField</code> tag for
-     * each Serializable field defined by an <code>ObjectStreamField</code>
-     * array component of <code>serialPersistentField</code>.
+     * {@code serial} tag<br>
+     * or return a single {@code FieldDoc} for
+     * {@code serialPersistentField} member.
+     * There should be a {@code serialField} tag for
+     * each Serializable field defined by an {@code ObjectStreamField}
+     * array component of {@code serialPersistentField}.
      *
-     * @return an array of <code>FieldDoc</code> objects for the Serializable
+     * @return an array of {@code FieldDoc} objects for the Serializable
      *         fields of this class or interface.
      *
      * @see #definesSerializableFields()
@@ -101,7 +113,10 @@
 
     /**
      *  Return true if Serializable fields are explicitly defined with
-     *  the special class member <code>serialPersistentFields</code>.
+     *  the special class member {@code serialPersistentFields}.
+     *
+     * @return true if Serializable fields are explicitly defined with
+     *         the special class member {@code serialPersistentFields}.
      *
      * @see #serializableFields()
      * @see SerialFieldTag
@@ -113,7 +128,7 @@
      * interface.
      *
      * <p> <i>This method cannot accommodate certain generic type constructs.
-     * The <code>superclassType</code> method should be used instead.</i>
+     * The {@code superclassType} method should be used instead.</i>
      *
      * @return the ClassDoc for the superclass of this class, null if
      *         there is no superclass.
@@ -124,7 +139,7 @@
     /**
      * Return the superclass of this class.  Return null if this is an
      * interface.  A superclass is represented by either a
-     * <code>ClassDoc</code> or a <code>ParametrizedType</code>.
+     * {@code ClassDoc} or a {@code ParametrizedType}.
      *
      * @return the superclass of this class, or null if there is no superclass.
      * @since 1.5
@@ -134,7 +149,7 @@
     /**
      * Test whether this class is a subclass of the specified class.
      * If this is an interface, return false for all classes except
-     * <code>java.lang.Object</code> (we must keep this unexpected
+     * {@code java.lang.Object} (we must keep this unexpected
      * behavior for compatibility reasons).
      *
      * @param cd the candidate superclass.
@@ -149,7 +164,7 @@
      * Return an empty array if there are no interfaces.
      *
      * <p> <i>This method cannot accommodate certain generic type constructs.
-     * The <code>interfaceTypes</code> method should be used instead.</i>
+     * The {@code interfaceTypes} method should be used instead.</i>
      *
      * @return an array of ClassDoc objects representing the interfaces.
      * @see #interfaceTypes
@@ -163,7 +178,7 @@
      * Return an empty array if there are no interfaces.
      *
      * @return an array of interfaces, each represented by a
-     *         <code>ClassDoc</code> or a <code>ParametrizedType</code>.
+     *         {@code ClassDoc} or a {@code ParametrizedType}.
      * @since 1.5
      */
     Type[] interfaceTypes();
@@ -225,7 +240,7 @@
      * Return
      * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
      * methods in this class or interface.
-     * Same as <code>methods(true)</code>.
+     * Same as {@code methods(true)}.
      *
      * @return an array of MethodDoc objects representing the included
      *         methods in this class or interface.  Does not include
@@ -243,6 +258,7 @@
      *               modifier option.
      *               Specify false to include all methods regardless of
      *               access modifier option.
+     *
      * @return       an array of MethodDoc objects representing the included
      *               methods in this class or interface.
      */
@@ -281,7 +297,7 @@
      * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
      * nested classes and interfaces within this class or interface.
      * This includes both static and non-static nested classes.
-     * (This method should have been named <code>nestedClasses()</code>,
+     * (This method should have been named {@code nestedClasses()},
      * as inner classes are technically non-static.)  Anonymous and local classes
      * or interfaces are not included.
      *
@@ -312,6 +328,8 @@
      * Search order: 1) qualified name, 2) nested in this class or interface,
      * 3) in this package, 4) in the class imports, 5) in the package imports.
      * Return the ClassDoc if found, null if not found.
+     * @param className Specify the class name to find as a String.
+     * @return the ClassDoc if found, null if not found.
      */
     ClassDoc findClass(String className);
 
--- a/src/share/classes/com/sun/javadoc/Doc.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/Doc.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2012, 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
@@ -43,6 +43,8 @@
     /**
      * Return the text of the comment for this doc item.
      * Tags have been removed.
+     *
+     * @return the text of the comment for this doc item.
      */
     String commentText();
 
@@ -119,6 +121,8 @@
      * Return the full unprocessed text of the comment.  Tags
      * are included as text.  Used mainly for store and retrieve
      * operations like internalization.
+     *
+     * @return the full unprocessed text of the comment.
      */
     String getRawCommentText();
 
@@ -126,6 +130,8 @@
      * Set the full unprocessed text of the comment.  Tags
      * are included as text.  Used mainly for store and retrieve
      * operations like internalization.
+     *
+     * @param rawDocumentation A String containing the full unprocessed text of the comment.
      */
     void setRawCommentText(String rawDocumentation);
 
@@ -143,7 +149,7 @@
      * <p>
      * This method satisfies the {@link java.lang.Comparable} interface.
      *
-     * @param   obj  the <code>Object</code> to be compared.
+     * @param   obj  the {@code Object} to be compared.
      * @return  a negative integer, zero, or a positive integer as this Object
      *      is less than, equal to, or greater than the given Object.
      * @exception ClassCastException the specified Object's type prevents it
@@ -250,6 +256,10 @@
      * Return true if this Doc item is
      * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
      * in the result set.
+     *
+     * @return true if this Doc item is
+     *         <a href="{@docRoot}/com/sun/javadoc/package-summary.html#included">included</a>
+     *         in the result set.
      */
     boolean isIncluded();
 
@@ -260,6 +270,10 @@
      * null because it has no location in the source file.
      *
      * @since 1.4
+     * @return the source positino of the first line of the
+     *         corresponding declaration, or null if
+     *         no position is available.  A default constructor returns
+     *         null because it has no location in the source file.
      */
     SourcePosition position();
 }
--- a/src/share/classes/com/sun/javadoc/Doclet.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/Doclet.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 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
@@ -29,15 +29,15 @@
  * This is an example of a starting class for a doclet,
  * showing the entry-point methods.  A starting class must
  * import com.sun.javadoc.* and implement the
- * <code>start(RootDoc)</code> method, as described in the
+ * {@code start(RootDoc)} method, as described in the
  * <a href="package-summary.html#package_description">package
  * description</a>.  If the doclet takes command line options,
- * it must also implement <code>optionLength</code> and
- * <code>validOptions</code>.
+ * it must also implement {@code optionLength} and
+ * {@code validOptions}.
  *
  * <p> A doclet supporting the language features added since 1.1
  * (such as generics and annotations) should indicate this
- * by implementing <code>languageVersion</code>.  In the absence of
+ * by implementing {@code languageVersion}.  In the absence of
  * this the doclet should not invoke any of the Doclet API methods
  * added since 1.5, and
  * the results of several other methods are modified so as
@@ -45,7 +45,7 @@
  * the doclet.
  *
  * <p> To start the doclet, pass
- * <code>-doclet</code> followed by the fully-qualified
+ * {@code -doclet} followed by the fully-qualified
  * name of the starting class on the javadoc tool command line.
  */
 public abstract class Doclet {
@@ -54,6 +54,7 @@
      * Generate documentation here.
      * This method is required for all doclets.
      *
+     * @param root Supply the RootDoc to the method.
      * @return true on success.
      */
     public static boolean start(RootDoc root) {
@@ -69,6 +70,7 @@
      * If this method is missing, Javadoc will print an invalid flag
      * error for every option.
      *
+     * @param option the option for which the number of arguements is returned.
      * @return number of arguments on the command line for an option
      *         including the option name itself.  Zero return means
      *         option not known.  Negative value means error occurred.
@@ -88,6 +90,8 @@
      * Printing option related error messages (using the provided
      * DocErrorReporter) is the responsibility of this method.
      *
+     * @param options Supply valid options as an array of Strings.
+     * @param reporter The DocErrorReporter responsible for these options.
      * @return true if the options are valid.
      */
     public static boolean validOptions(String options[][],
--- a/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java	Mon Mar 03 15:10:01 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
@@ -36,11 +36,11 @@
     /**
      * Return exceptions this method or constructor throws.
      * 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>The <code>thrownExceptions</code> method cannot
+     * <p> <i>The {@code thrownExceptions} method cannot
      * accommodate certain generic type constructs.  The
-     * <code>thrownExceptionTypes</code> method should be used
+     * {@code thrownExceptionTypes} method should be used
      * instead.</i>
      *
      * @return an array of ClassDoc[] representing the exceptions
@@ -53,19 +53,23 @@
      * Return exceptions this method or constructor throws.
      *
      * @return an array representing the exceptions thrown by this method.
-     *         Each array element is either a <code>ClassDoc</code> or a
-     *         <code>TypeVariable</code>.
+     *         Each array element is either a {@code ClassDoc} or a
+     *         {@code TypeVariable}.
      * @since 1.5
      */
     Type[] thrownExceptionTypes();
 
     /**
      * Return true if this method is native
+     *
+     * @return true if this method is native
      */
     boolean isNative();
 
     /**
      * Return true if this method is synchronized
+     *
+     * @return true if this method is synchronized
      */
     boolean isSynchronized();
 
@@ -74,6 +78,7 @@
      * of arguments.
      *
      * @since 1.5
+     * @return true if this method was declared to take a variable number of arguments.
      */
     public boolean isVarArgs();
 
@@ -98,8 +103,8 @@
     /**
      * Return the throws tags in this method.
      *
-     * @return an array of ThrowTag containing all <code>&#64;exception</code>
-     * and <code>&#64;throws</code> tags.
+     * @return an array of ThrowTag containing all {@code &#64;exception}
+     * and {@code &#64;throws} tags.
      */
     ThrowsTag[] throwsTags();
 
@@ -107,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</code> tags
+     * @return an array of ParamTag containing all {@code &#64;param} tags
      * corresponding to the parameters of this method.
      */
     ParamTag[] paramTags();
@@ -115,7 +120,7 @@
     /**
      * Return the type parameter tags in this method.
      *
-     * @return an array of ParamTag containing all <code>&#64;param</code> tags
+     * @return an array of ParamTag containing all {@code &#64;param} tags
      * corresponding to the type parameters of this method.
      * @since 1.5
      */
@@ -123,8 +128,10 @@
 
     /**
      * Get the signature. It is the parameter list, type is qualified.
-     *      For instance, for a method <code>mymethod(String x, int y)</code>,
-     *      it will return <code>(java.lang.String,int)</code>.
+     *      For instance, for a method {@code mymethod(String x, int y)},
+     *      it will return {@code (java.lang.String,int)}.
+     *
+     * @return the parameter list where type is qualified.
      */
     String signature();
 
@@ -132,8 +139,10 @@
      * get flat signature.  all types are not qualified.
      *      return a String, which is the flat signiture of this member.
      *      It is the parameter list, type is not qualified.
-     *      For instance, for a method <code>mymethod(String x, int y)</code>,
-     *      it will return <code>(String, int)</code>.
+     *      For instance, for a method {@code mymethod(String x, int y)},
+     *      it will return {@code (String, int)}.
+     *
+     * @return a String, which is the flat signiture of this member.
      */
     String flatSignature();
 
--- a/src/share/classes/com/sun/javadoc/FieldDoc.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/FieldDoc.java	Mon Mar 03 15:10:01 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
@@ -37,16 +37,22 @@
 
     /**
      * Get type of this field.
+     *
+     * @return the type of this field.
      */
     Type type();
 
     /**
      * Return true if this field is transient
+     *
+     * @return true if this field is transient
      */
     boolean isTransient();
 
     /**
      * Return true if this field is volatile
+     *
+     * @return true if this field is volatile
      */
     boolean isVolatile();
 
@@ -54,7 +60,7 @@
      * Return the serialField tags in this FieldDoc item.
      *
      * @return an array of <tt>SerialFieldTag</tt> objects containing
-     *         all <code>@serialField</code> tags.
+     *         all {@code @serialField} tags.
      */
     SerialFieldTag[] serialFieldTags();
 
--- a/src/share/classes/com/sun/javadoc/MemberDoc.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/MemberDoc.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 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
@@ -42,6 +42,8 @@
 
     /**
      * Returns true if this member was synthesized by the compiler.
+     *
+     * @return true if this member was synthesized by the compiler.
      */
     boolean isSynthetic();
 }
--- a/src/share/classes/com/sun/javadoc/MethodDoc.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/MethodDoc.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2012, 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
@@ -35,11 +35,15 @@
 
     /**
      * Return true if this method is abstract
+     *
+     * @return true if this method is abstract
      */
     boolean isAbstract();
 
     /**
      * Return true if this method is default
+     *
+     * @return true if this method is default
      */
     boolean isDefault();
 
@@ -54,9 +58,9 @@
     /**
      * Return the class containing the method that this method overrides.
      *
-     * <p> <i>The <code>overriddenClass</code> method cannot
+     * <p> <i>The {@code overriddenClass} method cannot
      * accommodate certain generic type constructs.  The
-     * <code>overriddenType</code> method should be used instead.</i>
+     * {@code overriddenType} method should be used instead.</i>
      *
      * @return a ClassDoc representing the superclass
      *         defining a method that this method overrides, or null if
@@ -66,7 +70,7 @@
 
     /**
      * Return the type containing the method that this method overrides.
-     * It may be a <code>ClassDoc</code> or a <code>ParameterizedType</code>.
+     * It may be a {@code ClassDoc} or a {@code ParameterizedType}.
      *
      * @return the supertype whose method is overridden, or null if this
      *         method does not override another in a superclass
--- a/src/share/classes/com/sun/javadoc/PackageDoc.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/PackageDoc.java	Mon Mar 03 15:10:01 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
@@ -122,6 +122,7 @@
     /**
      * Lookup a class or interface within this package.
      *
+     * @param className A String containing the name of the class to look up.
      * @return ClassDoc of found class or interface,
      * or null if not found.
      */
--- a/src/share/classes/com/sun/javadoc/Parameter.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/Parameter.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2004, 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
@@ -35,12 +35,16 @@
 
     /**
      * Get the type of this parameter.
+     *
+     * @return the type of this parameter.
      */
     Type type();
 
     /**
      * Get local name of this parameter.
      * For example if parameter is the short 'index', returns "index".
+     *
+     * @return the name of this parameter as a string.
      */
     String name();
 
@@ -51,6 +55,8 @@
      * This method returns a complete string
      * representation of the type, including the dimensions of arrays and
      * the type arguments of parameterized types.  Names are qualified.
+     *
+     * @return a complete string representation of the type.
      */
     String typeName();
 
--- a/src/share/classes/com/sun/javadoc/ProgramElementDoc.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/ProgramElementDoc.java	Mon Mar 03 15:10:01 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
@@ -57,10 +57,10 @@
 
     /**
      * Get the fully qualified name of this program element.
-     * For example, for the class <code>java.util.Hashtable</code>,
+     * For example, for the class {@code java.util.Hashtable},
      * return "java.util.Hashtable".
      * <p>
-     * For the method <code>bar()</code> in class <code>Foo</code>
+     * For the method {@code bar()} in class {@code Foo}
      * in the unnamed package, return "Foo.bar".
      *
      * @return the qualified name of the program element as a String.
@@ -71,6 +71,8 @@
      * Get the modifier specifier integer.
      *
      * @see java.lang.reflect.Modifier
+     *
+     * @return Get the modifier specifier integer.
      */
     int modifierSpecifier();
 
@@ -82,6 +84,8 @@
      * </pre>
      * return "public abstract".
      * Annotations are not included.
+     *
+     * @return "public abstract".
      */
     String modifiers();
 
@@ -96,30 +100,42 @@
 
     /**
      * Return true if this program element is public.
+     *
+     * @return true if this program element is public.
      */
     boolean isPublic();
 
     /**
      * Return true if this program element is protected.
+     *
+     * @return true if this program element is protected.
      */
     boolean isProtected();
 
     /**
      * Return true if this program element is private.
+     *
+     * @return true if this program element is private.
      */
     boolean isPrivate();
 
     /**
      * Return true if this program element is package private.
+     *
+     * @return true if this program element is package private.
      */
     boolean isPackagePrivate();
     /**
      * Return true if this program element is static.
+     *
+     * @return true if this program element is static.
      */
     boolean isStatic();
 
     /**
      * Return true if this program element is final.
+     *
+     * @return true if this program element is final.
      */
     boolean isFinal();
 }
--- a/src/share/classes/com/sun/javadoc/SeeTag.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/SeeTag.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2002, 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
@@ -31,11 +31,11 @@
  * 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}</code>, or a separate block comment,
- * using <code>@see</code>.
- * Method <code>name()</code> returns "@link" (no curly braces) or
+ * using {@code &#123;@link}}, or a separate block comment,
+ * using {@code @see}.
+ * Method {@code name()} returns "@link" (no curly braces) or
  * "@see", depending on the tag.
- * Method <code>kind()</code> returns "@see" for both tags.
+ * Method {@code kind()} returns "@see" for both tags.
  *
  * @author Kaiyang Liu (original)
  * @author Robert Field (rewrite)
@@ -45,44 +45,51 @@
 public interface SeeTag extends Tag {
 
     /**
-     * Get the label of the <code>@see</code> tag.
+     * Get the label of the {@code @see} tag.
      * Return null if no label is present.
      * For example, for:
      * <p>
-     *    &nbsp;&nbsp;<code>@see String#trim() the trim method</code>
+     *    &nbsp;&nbsp;{@code @see String#trim() the trim method}
      * </p>
      * return "the trim method".
+     *
+     * @return "the trim method".
      */
     String label();
 
     /**
-     * Get the package doc when <code>@see</code> references only a package.
+     * Get the package doc when {@code @see} references only a package.
      * Return null if the package cannot be found, or if
-     * <code>@see</code> references any other element (class,
+     * {@code @see} references any other element (class,
      * interface, field, constructor, method) or non-element.
      * For example, for:
      * <p>
-     *   &nbsp;&nbsp;<code>@see java.lang</code>
+     *   &nbsp;&nbsp;{@code @see java.lang}
      * </p>
-     * return the <code>PackageDoc</code> for <code>java.lang</code>.
+     * return the {@code PackageDoc} for {@code java.lang}.
+     *
+     * @return the {@code PackageDoc} for {@code java.lang}.
      */
     public PackageDoc referencedPackage();
 
     /**
-     * Get the class or interface name of the <code>@see</code> reference.
+     * Get the class or interface name of the {@code @see} reference.
      * The name is fully qualified if the name specified in the
-     * original <code>@see</code> tag was fully qualified, or if the class
+     * original {@code @see} tag was fully qualified, or if the class
      * or interface can be found; otherwise it is unqualified.
-     * If <code>@see</code> references only a package name, then return
+     * If {@code @see} references only a package name, then return
      * the package name instead.
      * For example, for:
      * <p>
-     *   &nbsp;&nbsp;<code>@see String#valueOf(java.lang.Object)</code>
+     *   &nbsp;&nbsp;{@code @see String#valueOf(java.lang.Object)}
      * </p>
      * return "java.lang.String".
-     * For "<code>@see java.lang</code>", return "java.lang".
-     * Return null if <code>@see</code> references a non-element, such as
-     * <code>@see &lt;a href="java.sun.com"&gt;</code>.
+     * 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;}.
+     *
+     * @return null if {@code @see} references a non-element, such as
+     * {@code @see &lt;a href="java.sun.com"&gt;}.
      */
     String referencedClassName();
 
@@ -91,36 +98,42 @@
      * Return null if the class cannot be found.
      * For example, for:
      * <p>
-     *   &nbsp;&nbsp;<code>@see String#valueOf(java.lang.Object)</code>
+     *   &nbsp;&nbsp;{@code @see String#valueOf(java.lang.Object)}
      * </p>
-     * return the <code>ClassDoc</code> for <code>java.lang.String</code>.
+     * return the {@code ClassDoc} for {@code java.lang.String}.
+     *
+     * @return the {@code ClassDoc} for {@code java.lang.String}.
      */
     ClassDoc referencedClass();
 
     /**
-     * Get the field, constructor or method substring of the <code>@see</code>
+     * Get the field, constructor or method substring of the {@code @see}
      * reference. Return null if the reference is to any other
      * element or to any non-element.
      * References to member classes (nested classes) return null.
      * For example, for:
      * <p>
-     *   &nbsp;&nbsp;<code>@see String#startsWith(String)</code>
+     *   &nbsp;&nbsp;{@code @see String#startsWith(String)}
      * </p>
      * return "startsWith(String)".
+     *
+     * @return "startsWith(String)".
      */
     String referencedMemberName();
 
     /**
      * Get the member doc for the field, constructor or method
-     * referenced by <code>@see</code>. Return null if the member cannot
+     * referenced by {@code @see}. Return null if the member cannot
      * be found or if the reference is to any other element or to any
      * non-element.
      * References to member classes (nested classes) return null.
      * For example, for:
      * <p>
-     *   &nbsp;&nbsp;<code>@see String#startsWith(java.lang.String)</code>
+     *   &nbsp;&nbsp;{@code @see String#startsWith(java.lang.String)}
      * </p>
-     * return the <code>MethodDoc</code> for <code>startsWith</code>.
+     * return the {@code MethodDoc} for {@code startsWith}.
+     *
+     * @return the {@code MethodDoc} for {@code startsWith}.
      */
     MemberDoc referencedMember();
 }
--- a/src/share/classes/com/sun/javadoc/SerialFieldTag.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/SerialFieldTag.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2012, 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
@@ -47,11 +47,15 @@
 
     /**
      * Return the serializable field name.
+     *
+     * @return the serializable field name.
      */
     public String fieldName();
 
     /**
      * Return the field type string.
+     *
+     * @return the field type string.
      */
     public String fieldType();
 
@@ -66,6 +70,9 @@
     /**
      * Return the field comment. If there is no serialField comment, return
      * javadoc comment of corresponding FieldDoc.
+     *
+     * @return the field comment. If there is no serialField comment, return
+     *         javadoc comment of corresponding FieldDoc.
      */
     public String description();
 
@@ -76,7 +83,7 @@
      * <p>
      * Included to make SerialFieldTag items java.lang.Comparable.
      *
-     * @param   obj the <code>Object</code> to be compared.
+     * @param   obj the {@code Object} to be compared.
      * @return  a negative integer, zero, or a positive integer as this Object
      *          is less than, equal to, or greater than the given Object.
      * @exception ClassCastException the specified Object's type prevents it
--- a/src/share/classes/com/sun/javadoc/SourcePosition.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/SourcePosition.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2002, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 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
@@ -36,17 +36,25 @@
  */
 public interface SourcePosition {
     /** The source file. Returns null if no file information is
-     *  available. */
+     *  available.
+     *
+     *  @return the source file as a File.
+     */
     File file();
 
     /** The line in the source file. The first line is numbered 1;
-     *  0 means no line number information is available. */
+     *  0 means no line number information is available.
+     *
+     *  @return the line number in the source file as an integer.
+     */
     int line();
 
     /** The column in the source file. The first column is
      *  numbered 1; 0 means no column information is available.
      *  Columns count characters in the input stream; a tab
      *  advances the column number to the next 8-column tab stop.
+     *
+     *  @return the column on the source line as an integer.
      */
     int column();
 
--- a/src/share/classes/com/sun/javadoc/Type.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/Type.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 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
@@ -28,8 +28,8 @@
 /**
  * Represents a type.  A type can be a class or interface, an
  * invocation (like {@code List<String>}) of a generic class or interface,
- * a type variable, a wildcard type ("<code>?</code>"),
- * or a primitive data type (like <code>char</code>).
+ * a type variable, a wildcard type ("{@code ?}"),
+ * or a primitive data type (like {@code char}).
  *
  * @since 1.2
  * @author Kaiyang Liu (original)
@@ -42,7 +42,8 @@
      * Return unqualified name of type excluding any dimension information.
      * <p>
      * For example, a two dimensional array of String returns
-     * "<code>String</code>".
+     * "{@code String}".
+     * @return unqualified name of type excluding any dimension information.
      */
     String typeName();
 
@@ -50,7 +51,8 @@
      * Return qualified name of type excluding any dimension information.
      *<p>
      * For example, a two dimensional array of String
-     * returns "<code>java.lang.String</code>".
+     * returns "{@code java.lang.String}".
+     * @return qualified name of this type excluding any dimension information.
      */
     String qualifiedTypeName();
 
@@ -60,9 +62,10 @@
      * only the identifier of the innermost type is included.
      * <p>
      * For example, the class {@code Outer.Inner} returns
-     * "<code>Inner</code>".
+     * "{@code Inner}".
      *
      * @since 1.5
+     * @return the simple name of this type excluding any dimension information.
      */
     String simpleTypeName();
 
@@ -70,7 +73,8 @@
      * Return the type's dimension information, as a string.
      * <p>
      * For example, a two dimensional array of String returns
-     * "<code>[][]</code>".
+     * "{@code [][]}".
+     * @return the type's dimension information as a string.
      */
     String dimension();
 
@@ -79,7 +83,7 @@
      * This includes any dimension information and type arguments.
      * <p>
      * For example, a two dimensional array of String may return
-     * "<code>java.lang.String[][]</code>",
+     * "{@code java.lang.String[][]}",
      * and the parameterized type {@code List<Integer>} may return
      * "{@code java.util.List<java.lang.Integer>}".
      *
@@ -96,66 +100,66 @@
     boolean isPrimitive();
 
     /**
-     * Return this type as a <code>ClassDoc</code> if it represents a class
+     * Return this type as a {@code ClassDoc} if it represents a class
      * or interface.  Array dimensions are ignored.
-     * If this type is a <code>ParameterizedType</code>,
-     * <code>TypeVariable</code>, or <code>WildcardType</code>, return
-     * the <code>ClassDoc</code> of the type's erasure.  If this is an
-     * <code>AnnotationTypeDoc</code>, return this as a <code>ClassDoc</code>
+     * If this type is a {@code ParameterizedType},
+     * {@code TypeVariable}, or {@code WildcardType}, return
+     * the {@code ClassDoc} of the type's erasure.  If this is an
+     * {@code AnnotationTypeDoc}, return this as a {@code ClassDoc}
      * (but see {@link #asAnnotationTypeDoc()}).
      * If this is a primitive type, return null.
      *
-     * @return the <code>ClassDoc</code> of this type,
+     * @return the {@code ClassDoc} of this type,
      *         or null if it is a primitive type.
      */
     ClassDoc asClassDoc();
 
     /**
-     * Return this type as a <code>ParameterizedType</code> if it represents
+     * Return this type as a {@code ParameterizedType} if it represents
      * an invocation of a generic class or interface.  Array dimensions
      * are ignored.
      *
-     * @return a <code>ParameterizedType</code> if the type is an
+     * @return a {@code ParameterizedType} if the type is an
      *         invocation of a generic type, or null if it is not.
      * @since 1.5
      */
     ParameterizedType asParameterizedType();
 
     /**
-     * Return this type as a <code>TypeVariable</code> if it represents
+     * Return this type as a {@code TypeVariable} if it represents
      * a type variable.  Array dimensions are ignored.
      *
-     * @return a <code>TypeVariable</code> if the type is a type variable,
+     * @return a {@code TypeVariable} if the type is a type variable,
      *         or null if it is not.
      * @since 1.5
      */
     TypeVariable asTypeVariable();
 
     /**
-     * Return this type as a <code>WildcardType</code> if it represents
+     * Return this type as a {@code WildcardType} if it represents
      * a wildcard type.
      *
-     * @return a <code>WildcardType</code> if the type is a wildcard type,
+     * @return a {@code WildcardType} if the type is a wildcard type,
      *         or null if it is not.
      * @since 1.5
      */
     WildcardType asWildcardType();
 
     /**
-     * Returns this type as a <code>AnnotatedType</code> if it represents
+     * Returns this type as a {@code AnnotatedType} if it represents
      * an annotated type.
      *
-     * @return a <code>AnnotatedType</code> if the type if an annotated type,
+     * @return a {@code AnnotatedType} if the type if an annotated type,
      *         or null if it is not
      * @since 1.8
      */
     AnnotatedType asAnnotatedType();
 
     /**
-     * Return this type as an <code>AnnotationTypeDoc</code> if it represents
+     * Return this type as an {@code AnnotationTypeDoc} if it represents
      * an annotation type.  Array dimensions are ignored.
      *
-     * @return an <code>AnnotationTypeDoc</code> if the type is an annotation
+     * @return an {@code AnnotationTypeDoc} if the type is an annotation
      *         type, or null if it is not.
      * @since 1.5
      */
@@ -165,7 +169,7 @@
      * If this type is an array type, return the element type of the
      * array. Otherwise, return null.
      *
-     * @return a <code>Type</code> representing the element type or null.
+     * @return a {@code Type} representing the element type or null.
      * @since 1.8
      */
     Type getElementType();
--- a/src/share/classes/com/sun/javadoc/TypeVariable.java	Mon Mar 03 15:03:17 2014 -0800
+++ b/src/share/classes/com/sun/javadoc/TypeVariable.java	Mon Mar 03 15:10:01 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, 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
@@ -59,6 +59,9 @@
     /**
      * Get the annotations of this program element.
      * Return an empty array if there are none.
+     *
+     * @return the annotations of this program element or
+     *         an empty array if there are none.
      */
     public AnnotationDesc[] annotations();