stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8035877: javadoc classes are missing @return and @param tags

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Neil Toda 2014-03-03 15:10:01 -08:00 committed by Jonathan Gibbons
parent 1f9569d235
commit 72641e4e7f
15 changed files with 225 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
langtools/src/share/classes/com/sun/javadoc/ClassDoc.java
View File

@ -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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
/**
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
/**
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
/**
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
/**
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
* 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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
* <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 @@ public interface ClassDoc extends ProgramElementDoc, Type {
* 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);

18
langtools/src/share/classes/com/sun/javadoc/Doc.java
View File

@ -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 @@ public interface Doc extends Comparable<Object> {
/**
* 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 @@ public interface Doc extends Comparable<Object> {
* 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 @@ public interface Doc extends Comparable<Object> {
* 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 @@ public interface Doc extends Comparable<Object> {
* <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 @@ public interface Doc extends Comparable<Object> {
* 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 @@ public interface Doc extends Comparable<Object> {
* 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();
}

16
langtools/src/share/classes/com/sun/javadoc/Doclet.java
View File

@ -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 @@ package com.sun.javadoc;
* 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 @@ package com.sun.javadoc;
* 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 @@ public abstract class Doclet {
* 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 @@ public abstract class Doclet {
* 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 @@ public abstract class Doclet {
* 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[][],

37
langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java
View File

@ -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 @@ public interface ExecutableMemberDoc extends MemberDoc {
/**
* 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 @@ public interface ExecutableMemberDoc extends MemberDoc {
* 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 @@ public interface ExecutableMemberDoc extends MemberDoc {
* 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 @@ public interface ExecutableMemberDoc extends MemberDoc {
/**
* 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 @@ public interface ExecutableMemberDoc extends MemberDoc {
* 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 @@ public interface ExecutableMemberDoc extends MemberDoc {
/**
* 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 @@ public interface ExecutableMemberDoc extends MemberDoc {
/**
* 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 @@ public interface ExecutableMemberDoc extends MemberDoc {
* 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();

10
langtools/src/share/classes/com/sun/javadoc/FieldDoc.java
View File

@ -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 @@ public interface FieldDoc extends MemberDoc {
/**
* 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 @@ public interface FieldDoc extends MemberDoc {
* 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();

4
langtools/src/share/classes/com/sun/javadoc/MemberDoc.java
View File

@ -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 @@ public interface MemberDoc extends ProgramElementDoc {
/**
* Returns true if this member was synthesized by the compiler.
*
* @return true if this member was synthesized by the compiler.
*/
boolean isSynthetic();
}

12
langtools/src/share/classes/com/sun/javadoc/MethodDoc.java
View File

@ -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 @@ public interface MethodDoc extends ExecutableMemberDoc {
/**
* 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 @@ public interface MethodDoc extends ExecutableMemberDoc {
/**
* 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 @@ public interface MethodDoc extends ExecutableMemberDoc {
/**
* 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

3
langtools/src/share/classes/com/sun/javadoc/PackageDoc.java
View File

@ -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 @@ public interface PackageDoc extends Doc {
/**
* 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.
*/

8
langtools/src/share/classes/com/sun/javadoc/Parameter.java
View File

@ -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 @@ public interface Parameter {
/**
* 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 @@ public interface Parameter {
* 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();

22
langtools/src/share/classes/com/sun/javadoc/ProgramElementDoc.java
View File

@ -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 @@ public interface ProgramElementDoc extends Doc {
/**
* 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 @@ public interface ProgramElementDoc extends Doc {
* Get the modifier specifier integer.
*
* @see java.lang.reflect.Modifier
*
* @return Get the modifier specifier integer.
*/
int modifierSpecifier();
@ -82,6 +84,8 @@ public interface ProgramElementDoc extends Doc {
* </pre>
* return "public abstract".
* Annotations are not included.
*
* @return "public abstract".
*/
String modifiers();
@ -96,30 +100,42 @@ public interface ProgramElementDoc extends Doc {
/**
* 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();
}

63
langtools/src/share/classes/com/sun/javadoc/SeeTag.java
View File

@ -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 @@ package com.sun.javadoc;
* 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 @@ package com.sun.javadoc;
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 @@ public interface SeeTag extends Tag {
* 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();
}

11
langtools/src/share/classes/com/sun/javadoc/SerialFieldTag.java
View File

@ -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 @@ public interface SerialFieldTag extends Tag, Comparable<Object> {
/**
* 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 @@ public interface SerialFieldTag extends Tag, Comparable<Object> {
/**
* 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 @@ public interface SerialFieldTag extends Tag, Comparable<Object> {
* <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

14
langtools/src/share/classes/com/sun/javadoc/SourcePosition.java
View File

@ -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 @@ import java.io.File;
*/
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();

54
langtools/src/share/classes/com/sun/javadoc/Type.java
View File

@ -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 @@ package com.sun.javadoc;
/**
* 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 @@ public interface Type {
* 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 @@ public interface Type {
* 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 @@ public interface Type {
* 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 @@ public interface Type {
* 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 @@ public interface Type {
* 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 @@ public interface Type {
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 @@ public interface Type {
* 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();

5
langtools/src/share/classes/com/sun/javadoc/TypeVariable.java
View File

@ -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 @@ public interface TypeVariable extends Type {
/**
* 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();