# HG changeset patch # User jjg # Date 1393888201 28800 # Node ID aa8958a4c8f4d09173eb0ae397ab5bc20ebbed5b # Parent 3c45d467788ffc3146018bc26c5c870704213746 8035877: javadoc classes are missing @return and @param tags Reviewed-by: jjg Contributed-by: neil.toda@oracle.com diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/ClassDoc.java --- 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 - * java.io.Serializable. + * {@code java.io.Serializable}. * - * Since java.io.Externalizable extends - * java.io.Serializable, + * 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 - * java.io.Externalizable. + * {@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. *

* Return either a list of default fields documented by - * serial tag
- * or return a single FieldDoc for - * serialPersistentField member. - * There should be a serialField tag for - * each Serializable field defined by an ObjectStreamField - * array component of serialPersistentField. + * {@code serial} tag
+ * 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 FieldDoc 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 serialPersistentFields. + * 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. * *

This method cannot accommodate certain generic type constructs. - * The superclassType method should be used instead. + * The {@code superclassType} method should be used instead. * * @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 - * ClassDoc or a ParametrizedType. + * {@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 - * java.lang.Object (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. * *

This method cannot accommodate certain generic type constructs. - * The interfaceTypes method should be used instead. + * The {@code interfaceTypes} method should be used instead. * * @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 - * ClassDoc or a ParametrizedType. + * {@code ClassDoc} or a {@code ParametrizedType}. * @since 1.5 */ Type[] interfaceTypes(); @@ -225,7 +240,7 @@ * Return * included * methods in this class or interface. - * Same as methods(true). + * 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 @@ * included * nested classes and interfaces within this class or interface. * This includes both static and non-static nested classes. - * (This method should have been named nestedClasses(), + * (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); diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/Doc.java --- 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 @@ *

* This method satisfies the {@link java.lang.Comparable} interface. * - * @param obj the Object 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 * included * in the result set. + * + * @return true if this Doc item is + * included + * 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(); } diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/Doclet.java --- 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 - * start(RootDoc) method, as described in the + * {@code start(RootDoc)} method, as described in the * package * description. If the doclet takes command line options, - * it must also implement optionLength and - * validOptions. + * it must also implement {@code optionLength} and + * {@code validOptions}. * *

A doclet supporting the language features added since 1.1 * (such as generics and annotations) should indicate this - * by implementing languageVersion. 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. * *

To start the doclet, pass - * -doclet 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[][], diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java --- 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 - * ClassDoc of its erasure. + * {@code ClassDoc} of its erasure. * - *

The thrownExceptions method cannot + *

The {@code thrownExceptions} method cannot * accommodate certain generic type constructs. The - * thrownExceptionTypes method should be used + * {@code thrownExceptionTypes} method should be used * instead. * * @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 ClassDoc or a - * TypeVariable. + * 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 @exception - * and @throws 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 @param 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 @param 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 mymethod(String x, int y), - * it will return (java.lang.String,int). + * 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 mymethod(String x, int y), - * it will return (String, int). + * 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(); diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/FieldDoc.java --- 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 SerialFieldTag objects containing - * all @serialField tags. + * all {@code @serialField} tags. */ SerialFieldTag[] serialFieldTags(); diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/MemberDoc.java --- 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(); } diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/MethodDoc.java --- 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. * - *

The overriddenClass method cannot + *

The {@code overriddenClass} method cannot * accommodate certain generic type constructs. The - * overriddenType method should be used instead. + * {@code overriddenType} method should be used instead. * * @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 ClassDoc or a ParameterizedType. + * 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 diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/PackageDoc.java --- 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. */ diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/Parameter.java --- 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(); diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/ProgramElementDoc.java --- 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 java.util.Hashtable, + * For example, for the class {@code java.util.Hashtable}, * return "java.util.Hashtable". *

- * For the method bar() in class Foo + * 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 @@ * * 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(); } diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/SeeTag.java --- 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 {@link}, or a separate block comment, - * using @see. - * Method name() 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 kind() 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 @see tag. + * Get the label of the {@code @see} tag. * Return null if no label is present. * For example, for: *

- *   @see String#trim() the trim method + *   {@code @see String#trim() the trim method} *

* return "the trim method". + * + * @return "the trim method". */ String label(); /** - * Get the package doc when @see 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 - * @see references any other element (class, + * {@code @see} references any other element (class, * interface, field, constructor, method) or non-element. * For example, for: *

- *   @see java.lang + *   {@code @see java.lang} *

- * return the PackageDoc for java.lang. + * 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 @see reference. + * Get the class or interface name of the {@code @see} reference. * The name is fully qualified if the name specified in the - * original @see 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 @see references only a package name, then return + * If {@code @see} references only a package name, then return * the package name instead. * For example, for: *

- *   @see String#valueOf(java.lang.Object) + *   {@code @see String#valueOf(java.lang.Object)} *

* return "java.lang.String". - * For "@see java.lang", return "java.lang". - * Return null if @see references a non-element, such as - * @see <a href="java.sun.com">. + * 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: *

- *   @see String#valueOf(java.lang.Object) + *   {@code @see String#valueOf(java.lang.Object)} *

- * return the ClassDoc for java.lang.String. + * 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 @see + * 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: *

- *   @see String#startsWith(String) + *   {@code @see String#startsWith(String)} *

* return "startsWith(String)". + * + * @return "startsWith(String)". */ String referencedMemberName(); /** * Get the member doc for the field, constructor or method - * referenced by @see. 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: *

- *   @see String#startsWith(java.lang.String) + *   {@code @see String#startsWith(java.lang.String)} *

- * return the MethodDoc for startsWith. + * return the {@code MethodDoc} for {@code startsWith}. + * + * @return the {@code MethodDoc} for {@code startsWith}. */ MemberDoc referencedMember(); } diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/SerialFieldTag.java --- 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 @@ *

* Included to make SerialFieldTag items java.lang.Comparable. * - * @param obj the Object 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 diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/SourcePosition.java --- 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(); diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/Type.java --- 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}) of a generic class or interface, - * a type variable, a wildcard type ("?"), - * or a primitive data type (like char). + * 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. *

* For example, a two dimensional array of String returns - * "String". + * "{@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. *

* For example, a two dimensional array of String - * returns "java.lang.String". + * 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. *

* For example, the class {@code Outer.Inner} returns - * "Inner". + * "{@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. *

* For example, a two dimensional array of String returns - * "[][]". + * "{@code [][]}". + * @return the type's dimension information as a string. */ String dimension(); @@ -79,7 +83,7 @@ * This includes any dimension information and type arguments. *

* For example, a two dimensional array of String may return - * "java.lang.String[][]", + * "{@code java.lang.String[][]}", * and the parameterized type {@code List} may return * "{@code java.util.List}". * @@ -96,66 +100,66 @@ boolean isPrimitive(); /** - * Return this type as a ClassDoc 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 ParameterizedType, - * TypeVariable, or WildcardType, return - * the ClassDoc of the type's erasure. If this is an - * AnnotationTypeDoc, return this as a ClassDoc + * 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 ClassDoc 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 ParameterizedType 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 ParameterizedType 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 TypeVariable if it represents + * Return this type as a {@code TypeVariable} if it represents * a type variable. Array dimensions are ignored. * - * @return a TypeVariable 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 WildcardType if it represents + * Return this type as a {@code WildcardType} if it represents * a wildcard type. * - * @return a WildcardType 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 AnnotatedType if it represents + * Returns this type as a {@code AnnotatedType} if it represents * an annotated type. * - * @return a AnnotatedType 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 AnnotationTypeDoc if it represents + * Return this type as an {@code AnnotationTypeDoc} if it represents * an annotation type. Array dimensions are ignored. * - * @return an AnnotationTypeDoc 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 Type representing the element type or null. + * @return a {@code Type} representing the element type or null. * @since 1.8 */ Type getElementType(); diff -r 3c45d467788f -r aa8958a4c8f4 langtools/src/share/classes/com/sun/javadoc/TypeVariable.java --- 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();