8010315: doclint errors in javac public API

Reviewed-by: darcy

langtools/make/build.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- Copyright (c) 2007, 2012, Oracle and/or its affiliates. All rights reserved.
+ Copyright (c) 2007, 2013, 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
@@ -432,6 +432,31 @@
         </zip>
     </target>
 
+    <target name="doclint-api" depends="build-all-classes">
+        <delete dir="${build.dir}/doclint/classes"/>
+        <mkdir dir="${build.dir}/doclint/classes"/>
+        <javac fork="true"
+               executable="${boot.javac}"
+               srcdir="${src.classes.dir}:${build.gensrc.dir}"
+               destdir="${build.dir}/doclint/classes"
+               includes="javax/lang/model/** com/sun/javadoc/** com/sun/source/**"
+               excludes=""
+               sourcepath="${javac.sourcepath}"
+               classpath="${javac.classpath}"
+               includeAntRuntime="no"
+               source="${javac.source}"
+               target="${javac.target}"
+               debug="${javac.debug}"
+               debuglevel="${javac.debuglevel}">
+            <compilerarg value="-implicit:none"/>
+            <compilerarg value="-Xprefer:source"/>
+            <compilerarg value="-J-Xbootclasspath/p:${build.bootstrap.dir}/classes"/>
+            <compilerarg line="${javac.no.jdk.warnings}"/>
+            <compilerarg line="${javac.version.opt}"/>
+            <compilerarg line="-Xdoclint:all/protected,-missing"/>
+        </javac>
+    </target>
+
     <!--
     **** Debugging/diagnostic targets.
     -->
@@ -678,7 +703,7 @@
                     jarclasspath="sjavac.jar"/>
         <build-tool name="sjavac"/>
     </target>
-    
+
     <!-- (no javadoc for javap) -->
 
     <target name="jtreg-sjavac" depends="build-sjavac,-def-jtreg">

langtools/src/share/classes/com/sun/source/util/DocTreeScanner.java

@@ -53,7 +53,7 @@ import com.sun.source.doctree.*;
  *
  * <p>Here is an example to count the number of erroneous nodes in a tree:
  * <pre>
- *   class CountErrors extends DocTreeScanner<Integer,Void> {
+ *   class CountErrors extends DocTreeScanner&lt;Integer,Void&gt; {
  *      {@literal @}Override
  *      public Integer visitErroneous(ErroneousTree node, Void p) {
  *          return 1;

langtools/src/share/classes/com/sun/source/util/JavacTask.java

@@ -56,7 +56,7 @@ public abstract class JavacTask implements CompilationTask {
      * If the compiler is being invoked using a
      * {@link javax.tools.JavaCompiler.CompilationTask CompilationTask},
      * then that task will be returned.
-     * @param processingEnvironment
+     * @param processingEnvironment the processing environment
      * @return the {@code JavacTask} for a {@code ProcessingEnvironment}
      * @since 1.8
      */

langtools/src/share/classes/com/sun/source/util/Plugin.java

@@ -38,7 +38,7 @@ import javax.tools.StandardLocation;
  *
  * <p>Plug-ins are located via a {@link ServiceLoader},
  * using the same class path as annotation processors (i.e.
- * {@link StandardLocation#PROCESSOR_PATH PROCESSOR_PATH} or
+ * {@link StandardLocation#ANNOTATION_PROCESSOR_PATH ANNOTATION_PROCESSOR_PATH} or
  * {@code -processorpath}).
  *
  * <p>It is expected that a typical plug-in will simply register a

langtools/src/share/classes/javax/lang/model/AnnotatedConstruct.java

@@ -25,16 +25,17 @@
 
 package javax.lang.model;
 
-import java.lang.annotation.Annotation;
+import java.lang.annotation.*;
 import java.util.List;
 import javax.lang.model.element.*;
+import javax.lang.model.type.*;
 
 /**
  * Represent a construct that can have annotations.
  *
- * When annotations are on an {@linkplain element.Element element},
- * the are on a <em>declaration</em>.  When annotations are on a {@linkplain
- * type.TypeMirror type}, they are on a <em>use</em> of a type.
+ * When annotations are on an {@linkplain Element element},
+ * they are on a <em>declaration</em>.  When annotations are on a {@linkplain
+ * TypeMirror type}, they are on a <em>use</em> of a type.
  *
  * @since 1.8
  */

langtools/src/share/classes/javax/lang/model/type/ExecutableType.java

@@ -85,7 +85,7 @@ public interface ExecutableType extends TypeMirror {
      *
      * An executable which is an instance method, or a constructor of an
      * inner class, has a receiver type derived from the {@linkplain
-     * #getEnclosingElement declaring type}.
+     * ExecutableElement#getEnclosingElement declaring type}.
      *
      * An executable which is a static method, or a constructor of a
      * non-inner class, or an initializer (static or instance), has no