8035877: javadoc classes are missing @return and @param tags
Reviewed-by: jjg
Contributed-by: neil.toda@oracle.com
--- a/langtools/src/share/classes/com/sun/javadoc/ClassDoc.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/Doc.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/Doclet.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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>@exception</code>
- * and <code>@throws</code> tags.
+ * @return an array of ThrowTag containing all {@code @exception}
+ * and {@code @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>@param</code> tags
+ * @return an array of ParamTag containing all {@code @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>@param</code> tags
+ * @return an array of ParamTag containing all {@code @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/langtools/src/share/classes/com/sun/javadoc/FieldDoc.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/MemberDoc.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/MethodDoc.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/PackageDoc.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/Parameter.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/ProgramElementDoc.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/SeeTag.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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>{@link}</code>, or a separate block comment,
- * using <code>@see</code>.
- * Method <code>name()</code> returns "@link" (no curly braces) or
+ * 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.
- * 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>
- * <code>@see String#trim() the trim method</code>
+ * {@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>
- * <code>@see java.lang</code>
+ * {@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>
- * <code>@see String#valueOf(java.lang.Object)</code>
+ * {@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 <a href="java.sun.com"></code>.
+ * 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">}.
+ *
+ * @return null if {@code @see} references a non-element, such as
+ * {@code @see <a href="java.sun.com">}.
*/
String referencedClassName();
@@ -91,36 +98,42 @@
* Return null if the class cannot be found.
* For example, for:
* <p>
- * <code>@see String#valueOf(java.lang.Object)</code>
+ * {@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>
- * <code>@see String#startsWith(String)</code>
+ * {@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>
- * <code>@see String#startsWith(java.lang.String)</code>
+ * {@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/langtools/src/share/classes/com/sun/javadoc/SerialFieldTag.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/SourcePosition.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/Type.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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/langtools/src/share/classes/com/sun/javadoc/TypeVariable.java Mon Mar 03 15:03:17 2014 -0800
+++ b/langtools/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();