# HG changeset patch # User jjg # Date 1393889071 28800 # Node ID 209daac13c8b552f7e40249d05cfa42ae1fb30fa # Parent aa8958a4c8f4d09173eb0ae397ab5bc20ebbed5b 8035878: javadoc tool documentation should be using {@code ..} specifier Reviewed-by: jjg Contributed-by: neil.toda@oracle.com diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/AnnotationValue.java --- a/langtools/src/share/classes/com/sun/javadoc/AnnotationValue.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/AnnotationValue.java Mon Mar 03 15:24:31 2014 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -38,11 +38,11 @@ * Returns the value. * The type of the returned object is one of the following: * * * @return the value. diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java --- a/langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/ExecutableMemberDoc.java Mon Mar 03 15:24:31 2014 -0800 @@ -103,8 +103,8 @@ /** * Return the throws tags in this method. * - * @return an array of ThrowTag containing all {@code @exception} - * and {@code @throws} tags. + * @return an array of ThrowTag containing all {@code @exception} + * and {@code @throws} tags. */ ThrowsTag[] throwsTags(); @@ -112,7 +112,7 @@ * Return the param tags in this method, excluding the type * parameter tags. * - * @return an array of ParamTag containing all {@code @param} tags + * @return an array of ParamTag containing all {@code @param} tags * corresponding to the parameters of this method. */ ParamTag[] paramTags(); @@ -120,7 +120,7 @@ /** * Return the type parameter tags in this method. * - * @return an array of ParamTag containing all {@code @param} tags + * @return an array of ParamTag containing all {@code @param} tags * corresponding to the type parameters of this method. * @since 1.5 */ diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/ParamTag.java --- a/langtools/src/share/classes/com/sun/javadoc/ParamTag.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/ParamTag.java Mon Mar 03 15:24:31 2014 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -38,7 +38,7 @@ /** * Return the name of the parameter or type parameter - * associated with this ParamTag. + * associated with this {@code ParamTag}. * The angle brackets delimiting a type parameter are not part of * its name. * @@ -48,18 +48,18 @@ /** * Return the parameter comment - * associated with this ParamTag. + * associated with this {@code ParamTag}. * * @return the parameter comment. */ String parameterComment(); /** - * Return true if this ParamTag corresponds to a type + * Return true if this {@code ParamTag} corresponds to a type * parameter. Return false if it corresponds to an ordinary parameter * of a method or constructor. * - * @return true if this ParamTag corresponds to a type + * @return true if this {@code ParamTag} corresponds to a type * parameter. * @since 1.5 */ diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/ParameterizedType.java --- a/langtools/src/share/classes/com/sun/javadoc/ParameterizedType.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/ParameterizedType.java Mon Mar 03 15:24:31 2014 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -97,10 +97,10 @@ * Return null is this is a top-level type. * *

For example, the containing type of - * {@code AnInterface.Nested} is the ClassDoc + * {@code AnInterface.Nested} is the {@code ClassDoc} * representing {@code AnInterface}, and the containing type of * {@code Outer.Inner} is the - * ParameterizedType representing {@code Outer}. + * {@code ParameterizedType} representing {@code Outer}. * * @return the type that contains this type as a member. */ diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/RootDoc.java --- a/langtools/src/share/classes/com/sun/javadoc/RootDoc.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/RootDoc.java Mon Mar 03 15:24:31 2014 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -60,7 +60,7 @@ * Return the packages * specified * on the command line. - * If -subpackages and -exclude options + * If {@code -subpackages} and {@code -exclude} options * are used, return all the non-excluded packages. * * @return packages specified on the command line. diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/SeeTag.java --- a/langtools/src/share/classes/com/sun/javadoc/SeeTag.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/SeeTag.java Mon Mar 03 15:24:31 2014 -0800 @@ -31,7 +31,7 @@ * plain text. (The plain text might be a reference * to something not online, such as a printed book, or be a hard-coded * HTML link.) The reference can either be inline with the comment, - * using {@code {@link}}, or a separate block comment, + * using {@code {@link}}, or a separate block comment, * using {@code @see}. * Method {@code name()} returns "@link" (no curly braces) or * "@see", depending on the tag. @@ -86,10 +86,10 @@ * return "java.lang.String". * For "{@code @see java.lang}", return "java.lang". * Return null if {@code @see} references a non-element, such as - * {@code @see <a href="java.sun.com">}. + * {@code @see }. * * @return null if {@code @see} references a non-element, such as - * {@code @see <a href="java.sun.com">}. + * {@code @see }. */ String referencedClassName(); diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/Tag.java --- a/langtools/src/share/classes/com/sun/javadoc/Tag.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/Tag.java Mon Mar 03 15:24:31 2014 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -33,7 +33,7 @@ * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since") * and tag text (e.g. "1.2"). Tags with structure or which require * special processing are handled by subclasses such as ParamTag - * (for @param), SeeTag (for @see and {@link}), and ThrowsTag + * (for @param), SeeTag (for @see and {@link}), and ThrowsTag * (for @throws). * * @author Robert Field @@ -50,10 +50,10 @@ /** * Return the name of this tag. The name is the string * starting with "@" that is used in a doc comment, such as - * @return. For inline tags, such as - * {@link}, the curly brackets + * {@code @return}. For inline tags, such as + * {@code {@link}}, the curly brackets * are not part of the name, so in this example the name - * would be simply @link. + * would be simply {@code @link}. * * @return the name of this tag */ @@ -69,7 +69,7 @@ /** * Return the kind of this tag. * For most tags, - * kind() == name(); + * {@code kind() == name()}; * the following table lists those cases where there is more * than one tag of a given kind: * @@ -101,27 +101,27 @@ String toString(); /** - * For a documentation comment with embedded {@link} - * tags, return an array of Tag objects. The entire + * For a documentation comment with embedded {@code {@link}} + * tags, return an array of {@code Tag} objects. The entire * doc comment is broken down into strings separated by - * {@link} tags, where each successive element + * {@code {@link}} tags, where each successive element * of the array represents either a string or - * {@link} tag, in order, from start to end. - * Each string is represented by a Tag object of + * {@code {@link}} tag, in order, from start to end. + * Each string is represented by a {@code Tag} object of * name "Text", where {@link #text()} returns the string. Each - * {@link} tag is represented by a + * {@code {@link}} tag is represented by a * {@link SeeTag} of name "@link" and kind "@see". * For example, given the following comment * tag: *

- * This is a {@link Doc commentlabel} example. + * {@code This is a {@link Doc commentlabel} example.} *

* return an array of Tag objects: *

diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/ThrowsTag.java --- a/langtools/src/share/classes/com/sun/javadoc/ThrowsTag.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/ThrowsTag.java Mon Mar 03 15:24:31 2014 -0800 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -39,7 +39,7 @@ /** * Return the name of the exception - * associated with this ThrowsTag. + * associated with this {@code ThrowsTag}. * * @return name of the exception. */ @@ -47,30 +47,30 @@ /** * Return the exception comment - * associated with this ThrowsTag. + * associated with this {@code ThrowsTag}. * * @return exception comment. */ String exceptionComment(); /** - * Return a ClassDoc that represents the exception. + * Return a {@code ClassDoc} that represents the exception. * If the type of the exception is a type variable, return the - * ClassDoc of its erasure. + * {@code ClassDoc} of its erasure. * *

This method cannot accommodate certain generic type - * constructs. The exceptionType method + * constructs. The {@code exceptionType} method * should be used instead. * - * @return ClassDoc that represents the exception. + * @return {@code ClassDoc} that represents the exception. * @see #exceptionType */ ClassDoc exception(); /** * Return the type of the exception - * associated with this ThrowsTag. - * This may be a ClassDoc or a TypeVariable. + * associated with this {@code ThrowsTag}. + * This may be a {@code ClassDoc} or a {@code TypeVariable}. * * @return the type of the exception. * @since 1.5 diff -r aa8958a4c8f4 -r 209daac13c8b langtools/src/share/classes/com/sun/javadoc/package-info.java --- a/langtools/src/share/classes/com/sun/javadoc/package-info.java Mon Mar 03 15:10:01 2014 -0800 +++ b/langtools/src/share/classes/com/sun/javadoc/package-info.java Mon Mar 03 15:24:31 2014 -0800 @@ -53,8 +53,8 @@ When calling javadoc, you pass in package names and source file names -- these are called the specified packages and classes. You also pass in Javadoc options; the access control Javadoc options -(-public, -protected, -package, -and -private) filter program elements, producing a +({@code -public}, {@code -protected}, {@code -package}, +and {@code -private}) filter program elements, producing a result set, called the included set, or "documented" set. (The unfiltered set is also available through {@link com.sun.javadoc.PackageDoc#allClasses(boolean) allClasses(false)}.) @@ -78,15 +78,15 @@ A qualified class or interface name is one that has its package -name prepended to it, such as java.lang.String. A non-qualified -name has no package name, such as String. +name prepended to it, such as {@code java.lang.String}. A non-qualified +name has no package name, such as {@code String}.

Example

The following is an example doclet that -displays information in the @param tags of the processed +displays information in the {@code @param} tags of the processed classes: 
 import com.sun.javadoc.*;
@@ -124,7 +124,7 @@
 superinterface of {@link com.sun.javadoc.MethodDoc} and
 {@link com.sun.javadoc.ConstructorDoc},
 and {@link com.sun.javadoc.ParamTag} holds information
-from "@param" tags.
+from "{@code @param}" tags.
 

 This doclet when invoked with a command line like: