8000208: fix langtools javadoc comment issues

Reviewed-by: bpatel, mcimadamore

src/share/classes/com/sun/javadoc/Tag.java

@@ -70,14 +70,14 @@ public interface Tag {
      * than one tag of a given kind:
      * <p>
      * <table border="1" cellpadding="4" cellspacing="0">
-     * <tr><th><tt> kind()  </th>  <th><tt> name()      </th></tr>
-     * <tr><td><tt> @throws </td>  <td><tt> @throws     </td></tr>
-     * <tr><td><tt> @throws </td>  <td><tt> @exception  </td></tr>
-     * <tr><td><tt> @see    </td>  <td><tt> @see        </td></tr>
-     * <tr><td><tt> @see    </td>  <td><tt> @link       </td></tr>
-     * <tr><td><tt> @see    </td>  <td><tt> @linkplain  </td></tr>
-     * <tr><td><tt> @serial </td>  <td><tt> @serial     </td></tr>
-     * <tr><td><tt> @serial </td>  <td><tt> @serialData </td></tr>
+     * <tr><th><tt> kind()  </tt></th>  <th><tt> name()      </tt></th></tr>
+     * <tr><td><tt> @throws </tt></td>  <td><tt> @throws     </tt></td></tr>
+     * <tr><td><tt> @throws </tt></td>  <td><tt> @exception  </tt></td></tr>
+     * <tr><td><tt> @see    </tt></td>  <td><tt> @see        </tt></td></tr>
+     * <tr><td><tt> @see    </tt></td>  <td><tt> @link       </tt></td></tr>
+     * <tr><td><tt> @see    </tt></td>  <td><tt> @linkplain  </tt></td></tr>
+     * <tr><td><tt> @serial </tt></td>  <td><tt> @serial     </tt></td></tr>
+     * <tr><td><tt> @serial </tt></td>  <td><tt> @serialData </tt></td></tr>
      * </table>
      */
     String kind();

src/share/classes/com/sun/tools/classfile/BootstrapMethods_attribute.java

 /*
- * Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2012, 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.tools.classfile;
 import java.io.IOException;
 
 /**
- * See JVMS <TBD>
- * http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm/
+ * See JVMS 4.7.21
+ * http://docs.oracle.com/javase/specs/jvms/se7/html/jvms-4.html#jvms-4.7.21
  *
  *  <p><b>This is NOT part of any supported API.
  *  If you write code that depends on this, you do so at your own risk.

src/share/classes/com/sun/tools/classfile/Dependencies.java

@@ -98,7 +98,7 @@ public class Dependencies {
          * Get the ClassFile object for a specified class.
          * @param className the name of the class to be returned.
          * @return the ClassFile for the given class
-         * @throws Dependencies#ClassFileNotFoundException if the classfile cannot be
+         * @throws Dependencies.ClassFileNotFoundException if the classfile cannot be
          *   found
          */
         public ClassFile getClassFile(String className)

src/share/classes/com/sun/tools/classfile/Instruction.java

 /*
- * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2012, 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
@@ -103,7 +103,7 @@ public class Instruction {
         R visitConstantPoolRefAndValue(Instruction instr, int index, int value, P p);
         /** See {@link Kind#LOCAL}. */
         R visitLocal(Instruction instr, int index, P p);
-        /** See {@link Kind#LOCAL_UBYTE}. */
+        /** See {@link Kind#LOCAL_BYTE}. */
         R visitLocalAndValue(Instruction instr, int index, int value, P p);
         /** See {@link Kind#DYNAMIC}. */
         R visitLookupSwitch(Instruction instr, int default_, int npairs, int[] matches, int[] offsets, P p);

src/share/classes/com/sun/tools/doclets/formats/html/AbstractExecutableMemberWriter.java

 /*
- * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2012, 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
@@ -81,7 +81,7 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
      * Add the summary link for the member.
      *
      * @param context the id of the context where the link will be printed
-     * @param classDoc the classDoc that we should link to
+     * @param cd the classDoc that we should link to
      * @param member the member being linked to
      * @param tdSummary the content tree to which the link will be added
      */
@@ -101,7 +101,7 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
     /**
      * Add the inherited summary link for the member.
      *
-     * @param classDoc the classDoc that we should link to
+     * @param cd the classDoc that we should link to
      * @param member the member being linked to
      * @param linksTree the content tree to which the link will be added
      */
@@ -138,7 +138,7 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
      * Add all the parameters for the executable member.
      *
      * @param member the member to write parameters for.
-     * @param tree the content tree to which the parameters information will be added.
+     * @param htmltree the content tree to which the parameters information will be added.
      */
     protected void addParameters(ExecutableMemberDoc member, Content htmltree) {
         addParameters(member, true, htmltree);
@@ -149,7 +149,7 @@ public abstract class AbstractExecutableMemberWriter extends AbstractMemberWrite
      *
      * @param member the member to write parameters for.
      * @param includeAnnotations true if annotation information needs to be added.
-     * @param tree the content tree to which the parameters information will be added.
+     * @param htmltree the content tree to which the parameters information will be added.
      */
     protected void addParameters(ExecutableMemberDoc member,
             boolean includeAnnotations, Content htmltree) {

src/share/classes/com/sun/tools/doclets/formats/html/AbstractMemberWriter.java

@@ -365,7 +365,7 @@ public abstract class AbstractMemberWriter {
      * Add the comment for the given member.
      *
      * @param member the member being documented.
-     * @param contentTree the content tree to which the comment will be added.
+     * @param htmltree the content tree to which the comment will be added.
      */
     protected void addComment(ProgramElementDoc member, Content htmltree) {
         if (member.inlineTags().length > 0) {

src/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java

@@ -188,8 +188,8 @@ public class ConfigurationImpl extends Configuration {
     // ClassWriter.
 
     /**
-     * Constructor. Initialises resource for the
-     * {@link com.sun.tools.doclets.MessageRetriever}.
+     * Constructor. Initializes resource for the
+     * {@link com.sun.tools.doclets.internal.toolkit.util.MessageRetriever MessageRetriever}.
      */
     private ConfigurationImpl() {
         standardmessage = new MessageRetriever(this,

src/share/classes/com/sun/tools/doclets/formats/html/DeprecatedListWriter.java

@@ -208,7 +208,7 @@ public class DeprecatedListWriter extends SubWriterHolderWriter {
      *
      * @param builder the deprecated list builder
      * @param type the type of list being documented
-     * @param contentTree the content tree to which the anchor will be added
+     * @param htmlTree the content tree to which the anchor will be added
      */
     private void addAnchor(DeprecatedAPIListBuilder builder, int type, Content htmlTree) {
         if (builder.hasDocumentation(type)) {

src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java

@@ -1407,7 +1407,7 @@ public class HtmlDocletWriter extends HtmlDocWriter {
     /**
      * Returns a package name label.
      *
-     * @param parsedName the package name
+     * @param packageName the package name
      * @return the package name content
      */
     public Content getPackageLabel(String packageName) {
@@ -2635,7 +2635,7 @@ public class HtmlDocletWriter extends HtmlDocWriter {
     /**
      * Adds the annotatation types for the given doc.
      *
-     * @param packageDoc the package to write annotations for
+     * @param doc the package to write annotations for
      * @param htmltree the content tree to which the annotation types will be added
      */
     public void addAnnotationInfo(ProgramElementDoc doc, Content htmltree) {

src/share/classes/com/sun/tools/doclets/formats/html/HtmlSerialFieldWriter.java

@@ -121,10 +121,10 @@ public class HtmlSerialFieldWriter extends FieldWriterImpl
     /**
      * Add the member header.
      *
-     * @param fieldsType the class document to be listed
-     * @param fieldTypeStr the string for the filed type to be documented
+     * @param fieldType the class document to be listed
+     * @param fieldTypeStr the string for the field type to be documented
      * @param fieldDimensions the dimensions of the field string to be added
-     * @param firldName name of the field to be added
+     * @param fieldName name of the field to be added
      * @param contentTree the content tree to which the member header will be added
      */
     public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,

src/share/classes/com/sun/tools/doclets/formats/html/LinkFactoryImpl.java

@@ -155,7 +155,6 @@ public class LinkFactoryImpl extends LinkFactory {
      * "../../java/lang/Object.html"
      *
      * @param linkInfo the information about the link.
-     * @param fileName the file name, to which path string is.
      */
     private String pathString(LinkInfoImpl linkInfo) {
         if (linkInfo.context == LinkInfoImpl.PACKAGE_FRAME) {

src/share/classes/com/sun/tools/doclets/formats/html/PackageIndexWriter.java

@@ -229,7 +229,7 @@ public class PackageIndexWriter extends AbstractPackageIndexWriter {
      * Adds the lower navigation bar and the bottom text
      * (from the -bottom option) at the bottom of page.
      *
-     * @param the documentation tree to which the navigation bar footer will be added
+     * @param body the documentation tree to which the navigation bar footer will be added
      */
     protected void addNavigationBarFooter(Content body) {
         addNavLinks(false, body);

src/share/classes/com/sun/tools/doclets/formats/html/SerializedFormWriterImpl.java

 /*
- * Copyright (c) 1998, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2012, 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,6 +29,7 @@ import java.io.*;
 import com.sun.javadoc.*;
 import com.sun.tools.doclets.formats.html.markup.*;
 import com.sun.tools.doclets.internal.toolkit.*;
+import com.sun.tools.doclets.internal.toolkit.util.DocletAbortException;
 
 /**
  * Generate the Serialized Form Information Page.

src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlTree.java

 /*
- * Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2012, 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
@@ -423,9 +423,9 @@ public class HtmlTree extends Content {
     /**
      * Generates a META tag with the http-equiv, content and charset attributes.
      *
-     * @param http-equiv http equiv attribute for the META tag
+     * @param httpEquiv http equiv attribute for the META tag
      * @param content type of content
-     * @param charset character set used
+     * @param charSet character set used
      * @return an HtmlTree object for the META tag
      */
     public static HtmlTree META(String httpEquiv, String content, String charSet) {

src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlWriter.java

 /*
- * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2012, 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
@@ -158,7 +158,7 @@ public class HtmlWriter extends PrintWriter {
      * @param docencoding Encoding to be used for this file.
      * @exception IOException Exception raised by the FileWriter is passed on
      * to next level.
-     * @exception UnSupportedEncodingException Exception raised by the
+     * @exception UnsupportedEncodingException Exception raised by the
      * OutputStreamWriter is passed on to next level.
      */
     public HtmlWriter(Configuration configuration,

src/share/classes/com/sun/tools/doclets/internal/toolkit/EnumConstantWriter.java

 /*
- * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2012, 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
@@ -56,7 +56,7 @@ public interface EnumConstantWriter {
      * Get the enum constants documentation tree header.
      *
      * @param enumConstant the enum constant being documented
-     * @param enumConstantDetailsTree the content tree representing enum constant details
+     * @param enumConstantsDetailsTree the content tree representing enum constant details
      * @return content tree for the enum constant documentation header
      */
     public Content getEnumConstantsTreeHeader(FieldDoc enumConstant,

src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/ConstantsSummaryBuilder.java

@@ -346,7 +346,6 @@ public class ConstantsSummaryBuilder extends AbstractBuilder {
 
         /**
          * Return the list of visible constant fields for the given classdoc.
-         * @param cd the classdoc to examine.
          * @return the list of visible constant fields for the given classdoc.
          */
         protected List<FieldDoc> members() {

src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java

@@ -166,7 +166,6 @@ public class MemberSummaryBuilder extends AbstractMemberBuilder {
      * This information can be used for doclet specific documentation
      * generation.
      *
-     * @param classDoc the {@link ClassDoc} we want to check.
      * @param type the type of members to return.
      * @return a list of methods that will be documented.
      * @see VisibleMemberMap

src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ParamTaglet.java

@@ -183,7 +183,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
      * Given an array of <code>ParamTag</code>s,return its string representation.
      * Try to inherit the param tags that are missing.
      *
-     * @param doc               the doc that holds the param tags.
+     * @param holder            the doc that holds the param tags.
      * @param writer            the TagletWriter that will write this tag.
      * @param formalParameters  The array of parmeters (from type or executable
      *                          member) to check.
@@ -256,7 +256,7 @@ public class ParamTaglet extends BaseTaglet implements InheritableTaglet {
      *        been documented.
      * @param rankMap a {@link java.util.Map} which holds ordering
      *                    information about the parameters.
-     * @param nameMap a {@link java.util.Map} which holds a mapping
+     * @param rankMap a {@link java.util.Map} which holds a mapping
      *                of a rank of a parameter to its name.  This is
      *                used to ensure that the right name is used
      *                when parameter documentation is inherited.

src/share/classes/com/sun/tools/doclets/internal/toolkit/taglets/ValueTaglet.java

@@ -108,7 +108,7 @@ public class ValueTaglet extends BaseInlineTaglet {
      * @param config the current configuration of the doclet.
      * @param tag the value tag.
      * @param name the name of the field to search for.  The name should be in
-     * <qualified class name>#<field name> format. If the class name is omitted,
+     * {@code <qualified class name>#<field name>} format. If the class name is omitted,
      * it is assumed that the field is in the current class.
      *
      * @return the corresponding FieldDoc. If the name is null or empty string,

src/share/classes/com/sun/tools/doclets/internal/toolkit/util/ClassDocCatalog.java

 /*
- * Copyright (c) 2001, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2012, 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
@@ -184,7 +184,7 @@ import com.sun.tools.doclets.internal.toolkit.Configuration;
       /**
        * Return all of the classes specified on the command-line that
        * belong to the given package.
-       * @param packageDoc the package to return the classes for.
+       * @param pkgDoc the package to return the classes for.
        */
       public ClassDoc[] allClasses(PackageDoc pkgDoc) {
           return pkgDoc.isIncluded() ?

src/share/classes/com/sun/tools/doclets/internal/toolkit/util/DeprecatedAPIListBuilder.java

@@ -146,7 +146,7 @@ public class DeprecatedAPIListBuilder {
     /**
      * Return the list of deprecated Doc objects of a given type.
      *
-     * @param the constant representing the type of list being returned.
+     * @param type the constant representing the type of list being returned.
      */
     public List<Doc> getList(int type) {
         return deprecatedLists.get(type);

src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Extern.java

@@ -91,7 +91,7 @@ public class Extern {
          * If the same package name is found in the map, then the first mapped
          * Item object or offline location will be retained.
          *
-         * @param packagename Package name found in the "package-list" file.
+         * @param packageName Package name found in the "package-list" file.
          * @param path        URL or Directory path from where the "package-list"
          * file is picked.
          * @param relative    True if path is URL, false if directory path.
@@ -179,7 +179,7 @@ public class Extern {
     /**
      * Get the Extern Item object associated with this package name.
      *
-     * @param pkgname Package name.
+     * @param pkgName Package name.
      */
     private Item findPackageItem(String pkgName) {
         if (packageToItemMap == null) {

src/share/classes/com/sun/tools/doclets/internal/toolkit/util/VisibleMemberMap.java

@@ -126,7 +126,7 @@ public class VisibleMemberMap {
      * Return the package private members inherited by the class.  Only return
      * if parent is package private and not documented.
      *
-     * @param configuation the current configuration of the doclet.
+     * @param configuration the current configuration of the doclet.
      * @return the package private members inherited by the class.
      */
     private List<ProgramElementDoc> getInheritedPackagePrivateMethods(Configuration configuration) {
@@ -149,7 +149,7 @@ public class VisibleMemberMap {
      * end of the list members that are inherited by inaccessible parents. We
      * document these members in the child because the parent is not documented.
      *
-     * @param configuation the current configuration of the doclet.
+     * @param configuration the current configuration of the doclet.
      */
     public List<ProgramElementDoc> getLeafClassMembers(Configuration configuration) {
         List<ProgramElementDoc> result = getMembersFor(classdoc);

src/share/classes/com/sun/tools/javac/api/DiagnosticFormatter.java

 /*
- * Copyright (c) 2008, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2012, 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
@@ -138,7 +138,7 @@ public interface DiagnosticFormatter<D extends Diagnostic<?>> {
         /**
          * Configure the set of diagnostic parts that should be displayed
          * by the formatter.
-         * @param options options to set
+         * @param visibleParts the parts to be set
          */
         public void setVisible(Set<DiagnosticPart> visibleParts);
 

src/share/classes/com/sun/tools/javac/api/JavacTool.java

 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -66,7 +66,7 @@ public final class JavacTool implements JavaCompiler {
      * Constructor used by service provider mechanism.  The recommended way to
      * obtain an instance of this class is by using {@link #create} or the
      * service provider mechanism.
-     * @see javax.tools.JavaCompilerTool
+     * @see javax.tools.JavaCompiler
      * @see javax.tools.ToolProvider
      * @see #create
      */

src/share/classes/com/sun/tools/javac/code/Printer.java

@@ -124,7 +124,7 @@ public abstract class Printer implements Type.Visitor<String, Locale>, Symbol.Vi
     /**
      * Get a localized string represenation for a given type.
      *
-     * @param ts type to be displayed
+     * @param t type to be displayed
      * @param locale the locale in which the string is to be rendered
      * @return localized string representation
      */
@@ -135,7 +135,7 @@ public abstract class Printer implements Type.Visitor<String, Locale>, Symbol.Vi
     /**
      * Get a localized string represenation for a given symbol.
      *
-     * @param ts symbol to be displayed
+     * @param s symbol to be displayed
      * @param locale the locale in which the string is to be rendered
      * @return localized string representation
      */

src/share/classes/com/sun/tools/javac/code/Symtab.java

@@ -301,7 +301,7 @@ public class Symtab {
     }
 
     /** Enter a class into symbol table.
-     *  @param    The name of the class.
+     *  @param s The name of the class.
      */
     private Type enterClass(String s) {
         return reader.enterClass(names.fromString(s)).type;

src/share/classes/com/sun/tools/javac/code/TypeTags.java

 /*
- * Copyright (c) 1999, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2012, 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
@@ -106,7 +106,7 @@ public class TypeTags {
      */
     public static final int DEFERRED = FORALL+1;
 
-    /** The tag of the bottom type <null>.
+    /** The tag of the bottom type {@code <null>}.
      */
     public static final int BOT = DEFERRED+1;
 

src/share/classes/com/sun/tools/javac/code/Types.java

@@ -1427,8 +1427,8 @@ public class Types {
      * conservative in that it is allowed to say that two types are
      * not disjoint, even though they actually are.
      *
-     * The type C<X> is castable to C<Y> exactly if X and Y are not
-     * disjoint.
+     * The type {@code C<X>} is castable to {@code C<Y>} exactly if
+     * {@code X} and {@code Y} are not disjoint.
      */
     public boolean disjointType(Type t, Type s) {
         return disjointType.visit(t, s);
@@ -1523,7 +1523,7 @@ public class Types {
      * something of type `t' can be a subtype of `s'? This is
      * different from the question "is `t' not a subtype of `s'?"
      * when type variables are involved: Integer is not a subtype of T
-     * where <T extends Number> but it is not true that Integer cannot
+     * where {@code <T extends Number>} but it is not true that Integer cannot
      * possibly be a subtype of T.
      */
     public boolean notSoftSubtype(Type t, Type s) {

src/share/classes/com/sun/tools/javac/comp/Attr.java

@@ -740,7 +740,7 @@ public class Attr extends JCTree.Visitor {
      *  @param env         The env for the const value
      *  @param initializer The initializer for the const value
      *  @param type        The expected type, or null
-     *  @see VarSymbol#setlazyConstValue
+     *  @see VarSymbol#setLazyConstValue
      */
     public Object attribLazyConstantValue(Env<AttrContext> env,
                                       JCTree.JCExpression initializer,

src/share/classes/com/sun/tools/javac/comp/Check.java

@@ -230,7 +230,6 @@ public class Check {
 
     /** Warn about unsafe vararg method decl.
      *  @param pos        Position to be used for error reporting.
-     *  @param sym        The deprecated symbol.
      */
     void warnUnsafeVararg(DiagnosticPosition pos, String key, Object... args) {
         if (lint.isEnabled(LintCategory.VARARGS) && allowSimplifiedVarargs)
@@ -397,7 +396,7 @@ public class Check {
  **************************************************************************/
 
     /** Return name of local class.
-     *  This is of the form    <enclClass> $ n <classname>
+     *  This is of the form   {@code <enclClass> $ n <classname> }
      *  where
      *    enclClass is the flat name of the enclosing class,
      *    classname is the simple name of the local class
@@ -600,11 +599,10 @@ public class Check {
 
     /** Check that a type is within some bounds.
      *
-     *  Used in TypeApply to verify that, e.g., X in V<X> is a valid
+     *  Used in TypeApply to verify that, e.g., X in {@code V<X>} is a valid
      *  type argument.
-     *  @param pos           Position to be used for error reporting.
      *  @param a             The type that should be bounded by bs.
-     *  @param bs            The bound.
+     *  @param bound         The bound.
      */
     private boolean checkExtends(Type a, Type bound) {
          if (a.isUnbound()) {
@@ -1262,8 +1260,10 @@ public class Check {
      *  their bounds. This must be done in a second phase after type attributon
      *  since a class might have a subclass as type parameter bound. E.g:
      *
+     *  <pre>{@code
      *  class B<A extends C> { ... }
      *  class C extends B<C> { ... }
+     *  }</pre>
      *
      *  and we can't make sure that the bound is already attributed because
      *  of possible cycles.
@@ -2574,7 +2574,7 @@ public class Check {
      * 'pos'.
      *
      * @param s The (annotation)type declaration annotated with a @ContainedBy
-     * @param containerAnno the @ContainedBy on 's'
+     * @param containedBy the @ContainedBy on 's'
      * @param pos where to report errors
      */
     public void validateContainedBy(TypeSymbol s, Attribute.Compound containedBy, DiagnosticPosition pos) {
@@ -3181,7 +3181,6 @@ public class Check {
      *  @param pos           Position for error reporting.
      *  @param sym           The symbol.
      *  @param s             The scope
-     *  @param staticImport  Whether or not this was a static import
      */
     boolean checkUniqueStaticImport(DiagnosticPosition pos, Symbol sym, Scope s) {
         return checkUniqueImport(pos, sym, s, true);

src/share/classes/com/sun/tools/javac/comp/Flow.java

@@ -148,7 +148,7 @@ import static com.sun.tools.javac.tree.JCTree.Tag.*;
  *  exception to this [no pun intended] is that checked exceptions that
  *  are known to be caught or declared to be caught in the enclosing
  *  method are not recorded in the queue, but instead are recorded in a
- *  global variable "Set<Type> thrown" that records the type of all
+ *  global variable "{@code Set<Type> thrown}" that records the type of all
  *  exceptions that can be thrown.
  *
  *  <p>Other minor issues the treatment of members of other classes

src/share/classes/com/sun/tools/javac/comp/Lower.java

@@ -671,7 +671,7 @@ public class Lower extends TreeTranslator {
     };
 
     /** Look up a synthetic name in a given scope.
-     *  @param scope        The scope.
+     *  @param s            The scope.
      *  @param name         The name.
      */
     private Symbol lookupSynthetic(Name name, Scope s) {
@@ -747,7 +747,7 @@ public class Lower extends TreeTranslator {
      *  This numbering scheme is used by the backend to decide whether
      *  to issue an invokevirtual or invokespecial call.
      *
-     *  @see Gen.visitSelect(Select tree)
+     *  @see Gen#visitSelect(JCFieldAccess tree)
      */
     private static final int
         DEREFcode = 0,

src/share/classes/com/sun/tools/javac/comp/MemberEnter.java

@@ -128,8 +128,7 @@ public class MemberEnter extends JCTree.Visitor implements Completer {
     /** Import all classes of a class or package on demand.
      *  @param pos           Position to be used for error reporting.
      *  @param tsym          The class or package the members of which are imported.
-     *  @param toScope   The (import) scope in which imported classes
-     *               are entered.
+     *  @param env           The env in which the imported classes will be entered.
      */
     private void importAll(int pos,
                            final TypeSymbol tsym,
@@ -150,8 +149,7 @@ public class MemberEnter extends JCTree.Visitor implements Completer {
     /** Import all static members of a class or package on demand.
      *  @param pos           Position to be used for error reporting.
      *  @param tsym          The class or package the members of which are imported.
-     *  @param toScope   The (import) scope in which imported classes
-     *               are entered.
+     *  @param env           The env in which the imported classes will be entered.
      */
     private void importStaticAll(int pos,
                                  final TypeSymbol tsym,

src/share/classes/com/sun/tools/javac/comp/TransTypes.java

@@ -132,17 +132,21 @@ public class TransTypes extends TreeTranslator {
      *  Then, coerce to some given target type unless target type is null.
      *  This operation is used in situations like the following:
      *
+     *  <pre>{@code
      *  class Cell<A> { A value; }
      *  ...
      *  Cell<Integer> cell;
      *  Integer x = cell.value;
+     *  }</pre>
      *
      *  Since the erasure of Cell.value is Object, but the type
      *  of cell.value in the assignment is Integer, we need to
      *  adjust the original type of cell.value to Object, and insert
      *  a cast to Integer. That is, the last assignment becomes:
      *
+     *  <pre>{@code
      *  Integer x = (Integer)cell.value;
+     *  }</pre>
      *
      *  @param tree       The expression tree whose type might need adjustment.
      *  @param erasedType The expression's type after erasure.

src/share/classes/com/sun/tools/javac/file/JavacFileManager.java

 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -805,8 +805,8 @@ public class JavacFileManager extends BaseFileManager implements StandardJavaFil
     }
 
     /**
-     * Enforces the specification of a "relative" URI as used in
-     * {@linkplain #getFileForInput(Location,String,URI)
+     * Enforces the specification of a "relative" name as used in
+     * {@linkplain #getFileForInput(Location,String,String)
      * getFileForInput}.  This method must follow the rules defined in
      * that method, do not make any changes without consulting the
      * specification.

src/share/classes/com/sun/tools/javac/file/Locations.java

@@ -53,13 +53,14 @@ import com.sun.tools.javac.util.Log;
 import com.sun.tools.javac.util.Options;
 
 import javax.tools.JavaFileManager;
+import javax.tools.StandardJavaFileManager;
 import static javax.tools.StandardLocation.*;
 import static com.sun.tools.javac.main.Option.*;
 
 /** This class converts command line arguments, environment variables
  *  and system properties (in File.pathSeparator-separated String form)
  *  into a boot class path, user class path, and source path (in
- *  Collection<String> form).
+ *  {@code Collection<String>} form).
  *
  *  <p><b>This is NOT part of any supported API.
  *  If you write code that depends on this, you do so at your own risk.
@@ -342,11 +343,11 @@ public class Locations {
             }
         }
 
-        /** @see JavaFileManager#handleOption. */
+        /** @see JavaFileManager#handleOption */
         abstract boolean handleOption(Option option, String value);
-        /** @see JavaFileManager#getLocation. */
+        /** @see StandardJavaFileManager#getLocation */
         abstract Collection<File> getLocation();
-        /** @see JavaFileManager#setLocation. */
+        /** @see StandardJavaFileManager#setLocation */
         abstract void setLocation(Iterable<? extends File> files) throws IOException;
     }
 

src/share/classes/com/sun/tools/javac/file/ZipFileIndex.java

@@ -59,7 +59,7 @@ import com.sun.tools.javac.file.RelativePath.RelativeFile;
  * the command line.)
  *
  * Location where to look for/generate optimized zip index files can be
- * provided using "-XDcachezipindexdir=<directory>". If this flag is not
+ * provided using "{@code -XDcachezipindexdir=<directory>}". If this flag is not
  * provided, the default location is the value of the "java.io.tmpdir" system
  * property.
  *

src/share/classes/com/sun/tools/javac/jvm/Gen.java

@@ -446,7 +446,7 @@ public class Gen extends JCTree.Visitor {
  * Normalizing class-members.
  *************************************************************************/
 
-    /** Distribute member initializer code into constructors and <clinit>
+    /** Distribute member initializer code into constructors and {@code <clinit>}
      *  method.
      *  @param defs         The list of class member declarations.
      *  @param c            The enclosing class.
@@ -689,7 +689,7 @@ public class Gen extends JCTree.Visitor {
      *  should be emitted, if so, put a new entry into CRTable
      *  and call method to generate bytecode.
      *  If not, just call method to generate bytecode.
-     *  @see    #genStat(Tree, Env)
+     *  @see    #genStat(JCTree, Env)
      *
      *  @param  tree     The tree to be visited.
      *  @param  env      The environment to use.
@@ -756,7 +756,7 @@ public class Gen extends JCTree.Visitor {
      *  should be emitted, if so, put a new entry into CRTable
      *  and call method to generate bytecode.
      *  If not, just call method to generate bytecode.
-     *  @see    #genCond(Tree,boolean)
+     *  @see    #genCond(JCTree,boolean)
      *
      *  @param  tree     The tree to be visited.
      *  @param  crtFlags The CharacterRangeTable flags

src/share/classes/com/sun/tools/javac/main/JavaCompiler.java

@@ -607,7 +607,7 @@ public class JavaCompiler implements ClassReader.SourceCompleter {
 
     /** Parse contents of input stream.
      *  @param filename     The name of the file from which input stream comes.
-     *  @param input        The input stream to be parsed.
+     *  @param content      The characters to be parsed.
      */
     protected JCCompilationUnit parse(JavaFileObject filename, CharSequence content) {
         long msec = now();
@@ -755,8 +755,6 @@ public class JavaCompiler implements ClassReader.SourceCompleter {
     /** Complete compiling a source file that has been accessed
      *  by the class file reader.
      *  @param c          The class the source file of which needs to be compiled.
-     *  @param filename   The name of the source file.
-     *  @param f          An input stream that reads the source file.
      */
     public void complete(ClassSymbol c) throws CompletionFailure {
 //      System.err.println("completing " + c);//DEBUG

src/share/classes/com/sun/tools/javac/nio/PathFileManager.java

 /*
- * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2012, 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
@@ -27,13 +27,14 @@ package com.sun.tools.javac.nio;
 
 import java.io.IOException;
 import java.nio.file.FileSystem;
+import java.nio.file.FileSystems;
 import java.nio.file.Path;
 import javax.tools.FileObject;
 import javax.tools.JavaFileManager;
 import javax.tools.JavaFileObject;
 
 /**
- *  File manager based on {@linkplain File java.nio.file.Path}.
+ *  File manager based on {@link java.nio.file.Path}.
  *
  *  Eventually, this should be moved to javax.tools.
  *  Also, JavaCompiler might reasonably provide a method getPathFileManager,

src/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java

@@ -108,8 +108,7 @@ public class JavaTokenizer {
      * {@code input[input.length -1]} is a white space character.
      *
      * @param fac the factory which created this Scanner
-     * @param input the input, might be modified
-     * @param inputLength the size of the input.
+     * @param buf the input, might be modified
      * Must be positive and less than or equal to input.length.
      */
     protected JavaTokenizer(ScannerFactory fac, CharBuffer buf) {

src/share/classes/com/sun/tools/javac/parser/Scanner.java

 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2012, 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
@@ -66,8 +66,7 @@ public class Scanner implements Lexer {
      * {@code input[input.length -1]} is a white space character.
      *
      * @param fac the factory which created this Scanner
-     * @param input the input, might be modified
-     * @param inputLength the size of the input.
+     * @param buf the input, might be modified
      * Must be positive and less than or equal to input.length.
      */
     protected Scanner(ScannerFactory fac, CharBuffer buf) {

src/share/classes/com/sun/tools/javac/parser/UnicodeReader.java

@@ -77,9 +77,8 @@ public class UnicodeReader {
      * that {@code inputLength < input.length} or
      * {@code input[input.length -1]} is a white space character.
      *
-     * @param fac the factory which created this Scanner
-     * @param input the input, might be modified
-     * @param inputLength the size of the input.
+     * @param sf the factory which created this Scanner
+     * @param buffer the input, might be modified
      * Must be positive and less than or equal to input.length.
      */
     protected UnicodeReader(ScannerFactory sf, CharBuffer buffer) {
@@ -255,16 +254,16 @@ public class UnicodeReader {
 
     /**
      * Returns a copy of a character array subset of the input buffer.
-     * The returned array begins at the <code>beginIndex</code> and
-     * extends to the character at index <code>endIndex - 1</code>.
-     * Thus the length of the substring is <code>endIndex-beginIndex</code>.
+     * The returned array begins at the {@code beginIndex} and
+     * extends to the character at index {@code endIndex - 1}.
+     * Thus the length of the substring is {@code endIndex-beginIndex}.
      * This behavior is like
-     * <code>String.substring(beginIndex, endIndex)</code>.
+     * {@code String.substring(beginIndex, endIndex)}.
      * Unicode escape sequences are not translated.
      *
      * @param beginIndex the beginning index, inclusive.
      * @param endIndex the ending index, exclusive.
-     * @throws IndexOutOfBounds if either offset is outside of the
+     * @throws ArrayIndexOutOfBoundsException if either offset is outside of the
      *         array bounds
      */
     public char[] getRawCharacters(int beginIndex, int endIndex) {

src/share/classes/com/sun/tools/javac/processing/JavacRoundEnvironment.java

 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -105,7 +105,7 @@ public class JavacRoundEnvironment implements RoundEnvironment {
      * Only type elements <i>included</i> in this round of annotation
      * processing, or declarations of members, parameters, or type
      * parameters declared within those, are returned.  Included type
-     * elements are {@linkplain #getSpecifiedTypeElements specified
+     * elements are {@linkplain #getRootElements specified
      * types} and any types nested within them.
      *
      * @param a  annotation type being requested

src/share/classes/com/sun/tools/javac/processing/ServiceProxy.java

 /*
- * Copyright (c) 2006, 2008, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2012, 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
@@ -72,7 +72,7 @@ class ServiceProxy {
      *         The service class for which providers are being sought;
      *         used to construct error detail strings
      *
-     * @param  url
+     * @param  u
      *         The URL naming the configuration file to be parsed
      *
      * @return true if the name of a service is found

src/share/classes/com/sun/tools/javac/tree/JCTree.java

@@ -464,32 +464,29 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
     }
 
     /**
-     * Everything in one source file is kept in a TopLevel structure.
-     * @param pid              The tree representing the package clause.
-     * @param sourcefile       The source file name.
-     * @param defs             All definitions in this file (ClassDef, Import, and Skip)
-     * @param packge           The package it belongs to.
-     * @param namedImportScope A scope for all named imports.
-     * @param starImportScope  A scope for all import-on-demands.
-     * @param lineMap          Line starting positions, defined only
-     *                         if option -g is set.
-     * @param docComments      A hashtable that stores all documentation comments
-     *                         indexed by the tree nodes they refer to.
-     *                         defined only if option -s is set.
-     * @param endPositions     An object encapsulating ending positions of source
-     *                         ranges indexed by the tree nodes they belong to.
-     *                         Defined only if option -Xjcov is set.
+     * Everything in one source file is kept in a {@linkplain JCCompilationUnit} structure.
      */
     public static class JCCompilationUnit extends JCTree implements CompilationUnitTree {
         public List<JCAnnotation> packageAnnotations;
+        /** The tree representing the package clause. */
         public JCExpression pid;
+        /** All definitions in this file (ClassDef, Import, and Skip) */
         public List<JCTree> defs;
+        /* The source file name. */
         public JavaFileObject sourcefile;
+        /** The package to which this compilation unit belongs. */
         public PackageSymbol packge;
+        /** A scope for all named imports. */
         public ImportScope namedImportScope;
+        /** A scope for all import-on-demands. */
         public StarImportScope starImportScope;
+        /** Line starting positions, defined only if option -g is set. */
         public Position.LineMap lineMap = null;
+        /** A table that stores all documentation comments indexed by the tree
+         * nodes they refer to. defined only if option -s is set. */
         public DocCommentTable docComments = null;
+        /* An object encapsulating ending positions of source ranges indexed by
+         * the tree nodes they belong to. Defined only if option -Xjcov is set. */
         public EndPosTable endPositions = null;
         protected JCCompilationUnit(List<JCAnnotation> packageAnnotations,
                         JCExpression pid,
@@ -550,10 +547,10 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * An import clause.
-     * @param qualid    The imported class(es).
      */
     public static class JCImport extends JCTree implements ImportTree {
         public boolean staticImport;
+        /** The imported class(es). */
         public JCTree qualid;
         protected JCImport(JCTree qualid, boolean importStatic) {
             this.qualid = qualid;
@@ -605,21 +602,21 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * A class definition.
-     * @param modifiers the modifiers
-     * @param name the name of the class
-     * @param typarams formal class parameters
-     * @param extending the classes this class extends
-     * @param implementing the interfaces implemented by this class
-     * @param defs all variables and methods defined in this class
-     * @param sym the symbol
      */
     public static class JCClassDecl extends JCStatement implements ClassTree {
+        /** the modifiers */
         public JCModifiers mods;
+        /** the name of the class */
         public Name name;
+        /** formal class parameters */
         public List<JCTypeParameter> typarams;
+        /** the classes this class extends */
         public JCExpression extending;
+        /** the interfaces implemented by this class */
         public List<JCExpression> implementing;
+        /** all variables and methods defined in this class */
         public List<JCTree> defs;
+        /** the symbol */
         public ClassSymbol sym;
         protected JCClassDecl(JCModifiers mods,
                            Name name,
@@ -676,24 +673,25 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * A method definition.
-     * @param modifiers method modifiers
-     * @param name method name
-     * @param restype type of method return value
-     * @param typarams type parameters
-     * @param params value parameters
-     * @param thrown exceptions thrown by this method
-     * @param stats statements in the method
-     * @param sym method symbol
      */
     public static class JCMethodDecl extends JCTree implements MethodTree {
+        /** method modifiers */
         public JCModifiers mods;
+        /** method name */
         public Name name;
+        /** type of method return value */
         public JCExpression restype;
+        /** type parameters */
         public List<JCTypeParameter> typarams;
+        /** value parameters */
         public List<JCVariableDecl> params;
+        /** exceptions thrown by this method */
         public List<JCExpression> thrown;
+        /** statements in the method */
         public JCBlock body;
-        public JCExpression defaultValue; // for annotation types
+        /** default value, for annotation types */
+        public JCExpression defaultValue;
+        /** method symbol */
         public MethodSymbol sym;
         protected JCMethodDecl(JCModifiers mods,
                             Name name,
@@ -748,17 +746,17 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * A variable definition.
-     * @param modifiers variable modifiers
-     * @param name variable name
-     * @param vartype type of the variable
-     * @param init variables initial value
-     * @param sym symbol
      */
     public static class JCVariableDecl extends JCStatement implements VariableTree {
+        /** variable modifiers */
         public JCModifiers mods;
+        /** variable name */
         public Name name;
+        /** type of the variable */
         public JCExpression vartype;
+        /** variable's initial value */
         public JCExpression init;
+        /** symbol */
         public VarSymbol sym;
         protected JCVariableDecl(JCModifiers mods,
                          Name name,
@@ -815,11 +813,11 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * A statement block.
-     * @param stats statements
-     * @param flags flags
      */
     public static class JCBlock extends JCStatement implements BlockTree {
+        /** flags */
         public long flags;
+        /** statements */
         public List<JCStatement> stats;
         /** Position of closing brace, optional. */
         public int endpos = Position.NOPOS;
@@ -1206,9 +1204,9 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * an expression statement
-     * @param expr expression structure
      */
     public static class JCExpressionStatement extends JCStatement implements ExpressionStatementTree {
+        /** expression structure */
         public JCExpression expr;
         protected JCExpressionStatement(JCExpression expr)
         {
@@ -1776,13 +1774,13 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * Selects through packages and classes
-     * @param selected selected Tree hierarchie
-     * @param selector name of field to select thru
-     * @param sym symbol of the selected class
      */
     public static class JCFieldAccess extends JCExpression implements MemberSelectTree {
+        /** selected Tree hierarchy */
         public JCExpression selected;
+        /** name of field to select thru */
         public Name name;
+        /** symbol of the selected class */
         public Symbol sym;
         protected JCFieldAccess(JCExpression selected, Name name, Symbol sym) {
             this.selected = selected;
@@ -1885,11 +1883,11 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * An identifier
-     * @param idname the name
-     * @param sym the symbol
      */
     public static class JCIdent extends JCExpression implements IdentifierTree {
+        /** the name */
         public Name name;
+        /** the symbol */
         public Symbol sym;
         protected JCIdent(Name name, Symbol sym) {
             this.name = name;
@@ -1912,10 +1910,10 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * A constant value given literally.
-     * @param value value representation
      */
     public static class JCLiteral extends JCExpression implements LiteralTree {
         public int typetag;
+        /** value representation */
         public Object value;
         protected JCLiteral(int typetag, Object value) {
             this.typetag = typetag;
@@ -1978,10 +1976,10 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * Identifies a basic type.
-     * @param tag the basic type id
      * @see TypeTags
      */
     public static class JCPrimitiveTypeTree extends JCExpression implements PrimitiveTypeTree {
+        /** the basic type id */
         public int typetag;
         protected JCPrimitiveTypeTree(int typetag) {
             this.typetag = typetag;
@@ -2105,11 +2103,11 @@ public abstract class JCTree implements Tree, Cloneable, DiagnosticPosition {
 
     /**
      * A formal class parameter.
-     * @param name name
-     * @param bounds bounds
      */
     public static class JCTypeParameter extends JCTree implements TypeParameterTree {
+        /** name */
         public Name name;
+        /** bounds */
         public List<JCExpression> bounds;
         protected JCTypeParameter(Name name, List<JCExpression> bounds) {
             this.name = name;

src/share/classes/com/sun/tools/javac/util/AbstractDiagnosticFormatter.java

 /*
- * Copyright (c) 2008, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2012, 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
@@ -484,7 +484,7 @@ public abstract class AbstractDiagnosticFormatter implements DiagnosticFormatter
         /**
          * Tells whether the caret display is active or not.
          *
-         * @param caretEnabled if true the caret is enabled
+         * @return true if the caret is enabled
          */
         public boolean isCaretEnabled() {
             return caretEnabled;

src/share/classes/com/sun/tools/javac/util/AbstractLog.java

 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2012, 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
@@ -132,7 +132,6 @@ public abstract class AbstractLog {
 
     /** Report a warning, unless suppressed by the  -nowarn option or the
      *  maximum number of warnings has been reached.
-     *  @param pos    The source position at which to report the warning.
      *  @param key    The key for the localized warning message.
      *  @param args   Fields of the warning message.
      */

src/share/classes/com/sun/tools/javac/util/BasicDiagnosticFormatter.java

 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -69,7 +69,7 @@ public class BasicDiagnosticFormatter extends AbstractDiagnosticFormatter {
     /**
      * Create a basic formatter based on the supplied options.
      *
-     * @param opts list of command-line options
+     * @param options list of command-line options
      * @param msgs JavacMessages object used for i18n
      */
     public BasicDiagnosticFormatter(Options options, JavacMessages msgs) {
@@ -329,7 +329,7 @@ public class BasicDiagnosticFormatter extends AbstractDiagnosticFormatter {
          * Set the indentation level for various element of a given diagnostic -
          * this might lead to more readable diagnostics
          *
-         * @param indentationKind kind of indentation to be set
+         * @param diagPart
          * @param nSpaces amount of spaces for the specified diagnostic part
          */
         public void setIndentation(DiagnosticPart diagPart, int nSpaces) {
@@ -384,7 +384,7 @@ public class BasicDiagnosticFormatter extends AbstractDiagnosticFormatter {
         /**
          * Get a metachar string for a specific format
          *
-         * @param sourcePos a positioning value for source line
+         * @param kind the format kind for which to get the metachar string
          */
         public String getFormat(BasicFormatKind kind) {
             return availableFormats.get(kind);

src/share/classes/com/sun/tools/javac/util/Context.java

@@ -44,7 +44,7 @@ import java.util.*;
  * instance method that is overridden in extended components.  A base
  * phase supporting extension would look something like this:
  *
- * <p><pre>
+ * <p><pre>{@code
  * public class Phase {
  *     protected static final Context.Key<Phase> phaseKey =
  *         new Context.Key<Phase>();
@@ -62,7 +62,7 @@ import java.util.*;
  *         // other intitialization follows...
  *     }
  * }
- * </pre>
+ * }</pre>
  *
  * <p>In the compiler, we simply use Phase.instance(context) to get
  * the reference to the phase.  But in extensions of the compiler, we
@@ -70,7 +70,7 @@ import java.util.*;
  * and this must be done before any reference to the phase is accessed
  * using Phase.instance().  An extended phase might be declared thus:
  *
- * <p><pre>
+ * <p><pre>{@code
  * public class NewPhase extends Phase {
  *     protected NewPhase(Context context) {
  *         super(context);
@@ -83,7 +83,7 @@ import java.util.*;
  *         });
  *     }
  * }
- * </pre>
+ * }</pre>
  *
  * <p>And is registered early in the extended compiler like this
  *

src/share/classes/com/sun/tools/javac/util/JCDiagnostic.java

@@ -213,7 +213,6 @@ public class JCDiagnostic implements Diagnostic<JavaFileObject> {
          * Create a new diagnostic of the given kind, which is not mandatory and which has
          * no lint category.
          *  @param kind        The diagnostic kind
-         *  @param ls          The lint category, if applicable, or null
          *  @param source      The source of the compilation unit, if any, in which to report the message.
          *  @param pos         The source position at which to report the message.
          *  @param key         The key for the localized message.
@@ -228,7 +227,7 @@ public class JCDiagnostic implements Diagnostic<JavaFileObject> {
          * Create a new diagnostic of the given kind.
          *  @param kind        The diagnostic kind
          *  @param lc          The lint category, if applicable, or null
-         *  @param isMandatory is diagnostic mandatory?
+         *  @param flags       The set of flags for the diagnostic
          *  @param source      The source of the compilation unit, if any, in which to report the message.
          *  @param pos         The source position at which to report the message.
          *  @param key         The key for the localized message.
@@ -363,7 +362,7 @@ public class JCDiagnostic implements Diagnostic<JavaFileObject> {
 
     /**
      * Create a diagnostic object.
-     * @param fomatter the formatter to use for the diagnostic
+     * @param formatter the formatter to use for the diagnostic
      * @param dt the type of diagnostic
      * @param lc     the lint category for the diagnostic
      * @param source the name of the source file, or null if none.

src/share/classes/com/sun/tools/javac/util/Position.java

@@ -80,11 +80,11 @@ public class Position {
 
     /** Encode line and column numbers in an integer as:
      *  {@code line-number << LINESHIFT + column-number }.
-     *  {@link Position.NOPOS} represents an undefined position.
+     *  {@link Position#NOPOS} represents an undefined position.
      *
      * @param  line  number of line (first is 1)
      * @param  col   number of character on line (first is 1)
-     * @return       an encoded position or {@link Position.NOPOS}
+     * @return       an encoded position or {@link Position#NOPOS}
      *               if the line or column number is too big to
      *               represent in the encoded format
      * @throws IllegalArgumentException if line or col is less than 1

src/share/classes/com/sun/tools/javac/util/RawDiagnosticFormatter.java

 /*
- * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2012, 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
@@ -52,7 +52,7 @@ public final class RawDiagnosticFormatter extends AbstractDiagnosticFormatter {
 
     /**
      * Create a formatter based on the supplied options.
-     * @param msgs
+     * @param options
      */
     public RawDiagnosticFormatter(Options options) {
         super(null, new SimpleConfiguration(options,

src/share/classes/com/sun/tools/javadoc/ClassDocImpl.java

@@ -844,7 +844,7 @@ public class ClassDocImpl extends ProgramElementDocImpl implements ClassDoc {
      * Note that this is not necessarily what the compiler would do!
      *
      * @param methodName the unqualified name to search for.
-     * @param paramTypeArray the array of Strings for method parameter types.
+     * @param paramTypes the array of Strings for method parameter types.
      * @return the first MethodDocImpl which matches, null if not found.
      */
     public MethodDocImpl findMethod(String methodName, String[] paramTypes) {
@@ -971,7 +971,7 @@ public class ClassDocImpl extends ProgramElementDocImpl implements ClassDoc {
      * Find constructor in this class.
      *
      * @param constrName the unqualified name to search for.
-     * @param paramTypeArray the array of Strings for constructor parameters.
+     * @param paramTypes the array of Strings for constructor parameters.
      * @return the first ConstructorDocImpl which matches, null if not found.
      */
     public ConstructorDoc findConstructor(String constrName,

src/share/classes/com/sun/tools/javadoc/DocImpl.java

@@ -262,7 +262,7 @@ public abstract class DocImpl implements Doc, Comparable<Object> {
      * <p>
      * Included so that Doc item are java.lang.Comparable.
      *
-     * @param   o 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

src/share/classes/com/sun/tools/javadoc/JavadocTool.java

 /*
- * Copyright (c) 2001, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2012, 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
@@ -386,7 +386,7 @@ public class JavadocTool extends com.sun.tools.javac.main.JavaCompiler {
     /**
      * Return true if given file name is a valid class name
      * (including "package-info").
-     * @param clazzname the name of the class to check.
+     * @param s the name of the class to check.
      * @return true if given class name is a valid class name
      * and false otherwise.
      */

src/share/classes/com/sun/tools/javadoc/ModifierFilter.java

 /*
- * Copyright (c) 2000, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2012, 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
@@ -32,7 +32,7 @@ import static com.sun.tools.javac.code.Flags.*;
  *   Filtering is done by returning boolean values.
  *   Classes, methods and fields can be filtered, or filtering
  *   can be done directly on modifier bits.
- *   @see com.sun.tools.javac.code.Flags;
+ *   @see com.sun.tools.javac.code.Flags
  *   @author Robert Field
  */
 

src/share/classes/com/sun/tools/javadoc/ParamTagImpl.java

 /*
- * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2012, 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
@@ -101,8 +101,8 @@ class ParamTagImpl extends TagImpl implements ParamTag {
      * TagImpls consisting of SeeTagImpl(s) and text containing TagImpl(s).
      *
      * @return TagImpl[] Array of tags with inline SeeTagImpls.
-     * @see TagImpl#inlineTagImpls()
-     * @see ThrowsTagImpl#inlineTagImpls()
+     * @see TagImpl#inlineTags()
+     * @see ThrowsTagImpl#inlineTags()
      */
     @Override
     public Tag[] inlineTags() {

src/share/classes/com/sun/tools/javadoc/ThrowsTagImpl.java

 /*
- * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2012, 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
@@ -108,8 +108,8 @@ class ThrowsTagImpl extends TagImpl implements ThrowsTag {
      * TagImpls consisting of SeeTagImpl(s) and text containing TagImpl(s).
      *
      * @return TagImpl[] Array of tags with inline SeeTagImpls.
-     * @see TagImpl#inlineTagImpls()
-     * @see ParamTagImpl#inlineTagImpls()
+     * @see TagImpl#inlineTags()
+     * @see ParamTagImpl#inlineTags()
      */
     @Override
     public Tag[] inlineTags() {

src/share/classes/com/sun/tools/javah/NativeHeaderTool.java

 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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,11 +29,13 @@ import java.io.Writer;
 import java.nio.charset.Charset;
 import java.util.Locale;
 import java.util.concurrent.Callable;
+import javax.tools.Diagnostic;
 import javax.tools.DiagnosticListener;
 import javax.tools.JavaFileManager;
 import javax.tools.JavaFileObject;
 import javax.tools.OptionChecker;
 import javax.tools.StandardJavaFileManager;
+import javax.tools.StandardLocation;
 import javax.tools.Tool;
 
 /**

src/share/classes/com/sun/tools/javap/DisassemblerTool.java

 /*
- * Copyright (c) 2005, 2008, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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,11 +29,13 @@ import java.io.Writer;
 import java.nio.charset.Charset;
 import java.util.Locale;
 import java.util.concurrent.Callable;
+import javax.tools.Diagnostic;
 import javax.tools.DiagnosticListener;
 import javax.tools.JavaFileManager;
 import javax.tools.JavaFileObject;
 import javax.tools.OptionChecker;
 import javax.tools.StandardJavaFileManager;
+import javax.tools.StandardLocation;
 import javax.tools.Tool;
 
 /**
@@ -69,9 +71,7 @@ public interface DisassemblerTool extends Tool, OptionChecker {
      * @param options compiler options, {@code null} means no options
      * @param classes class names (for annotation processing), {@code
      * null} means no class names
-     * @param compilationUnits the compilation units to compile, {@code
-     * null} means no compilation units
-     * @return an object representing the compilation
+     * @return a task to perform the disassembly
      * @throws RuntimeException if an unrecoverable error
      * occurred in a user supplied component.  The
      * {@linkplain Throwable#getCause() cause} will be the error in