Cleanup javadocs. This makes the following changes:

1) Stop using doclava. It has too many bugs (like dropping annotations). 2) Tell javadoc not to doclint. Java8 does it and errs if it fails. 3) Link to appropriate third parties from javadoc. 4) Split extensions into separate groups in ant javadoc. 5) Cleanup code that had javadoc warnings.
agent-mo · Jul 20, 2014 · 6b3086d · 6b3086d
1 parent 1aa8696
commit 6b3086d
Show file tree

Hide file tree

Showing 13 changed files with 126 additions and 92 deletions.
diff --git a/build.xml b/build.xml
@@ -8,6 +8,14 @@
     <fileset dir="${lib.dir}" includes="*.jar"/>
     <fileset dir="${lib.dir}/build" includes="*.jar"/>
   </path>
+
+  <path id="javadoc.classpath">
+  	<path refid="compile.classpath"/>
+    <fileset dir="extensions">
+    	<include name="*/lib/*.jar"/>
+    </fileset>
+    <pathelement location="${build.dir}/classes"/>
+  </path>
 
 
   <target name="jar" depends="jar.withdeps, manifest" description="Build jar.">
@@ -130,7 +138,7 @@
 
   <property name="old.api" value="3.0"/>
   <property name="new.api" value="latest"/>
-  <target name="jdiff">
+  <target name="jdiff" depends="compile">
     <property name="jdiff.home" value="lib/build/jdiff"/>
     <property name="jdiff.tmp" value="build/docs/latest-api-diffs"/>
     <delete dir="${jdiff.tmp}"/>
@@ -140,7 +148,7 @@
     <javadoc packagenames="com.google.*"
              docletpath="${jdiff.home}/jdiff.jar${path.separator}${jdiff.home}/xerces.jar"
              maxmemory="1024M"
-             classpath="lib/javax.inject.jar${path.separator}lib/aopalliance.jar${path.separator}lib/guava-16.0.1.jar">
+             classpathref="javadoc.classpath">
       <fileset dir="${src.dir}" defaultexcludes="yes">
         <include name="com/google/**"/>
         <exclude name="com/google/inject/internal/**"/>
@@ -169,7 +177,7 @@
              docletpath="${jdiff.home}/jdiff.jar${path.separator}${jdiff.home}/xerces.jar"
              maxmemory="512M"
              sourcefiles="${jdiff.home}/Null.java"
-             classpath="lib/javax.inject.jar${path.separator}lib/aopalliance.jar${path.separator}lib/guava-16.0.1.jar">
+             classpathref="javadoc.classpath">
       <doclet name="jdiff.JDiff">
         <param name="-oldapi" value="${old.api}"/>
         <param name="-oldapidir" value="latest-api-diffs"/>
@@ -183,47 +191,60 @@
     </javadoc>
   </target>
 
-  <target name="javadoc">
+  <target name="javadoc" depends="compile">
     <javadoc packagenames="com.google.*"
-             destdir="build/docs"
-             docletpath="lib/build/doclava.jar"
-             bootclasspath="${java.home}/lib/rt.jar"
+             destdir="build/docs/javadoc"
              maxmemory="512M"
-             classpath="lib/javax.inject.jar${path.separator}lib/aopalliance.jar${path.separator}lib/guava-16.0.1.jar{$path.separator}lib/build/jsr305.jar">
+             classpathref="javadoc.classpath"
+             additionalparam="-Xdoclint:none"
+             windowtitle="Guice ${new.api} API"
+             author="false"
+             protected="true">
+      <group title="Guice Core" packages="com.google.inject:com.google.inject.util:com.google.inject.spi:com.google.inject.name:com.google.inject.matcher:com.google.inject.binder"/>
       <fileset dir="${src.dir}" defaultexcludes="yes">
-        <include name="com/google/**"/>
+        <include name="com/google/inject/**"/>
         <exclude name="com/google/inject/internal/**"/>
-      </fileset>
+      </fileset>      
+
+      <group title="Servlet Extension" packages="com.google.inject.servlet"/>
       <fileset dir="${servlet.src.dir}"/>
-      <fileset dir="${spring.src.dir}"/>
+
+      <group title="AssistedInject Extension" packages="com.google.inject.assistedinject"/>
       <fileset dir="${assistedinject.src.dir}"/>
-      <fileset dir="${jmx.src.dir}"/>
-      <fileset dir="${jndi.src.dir}"/>
-      <fileset dir="${throwingproviders.src.dir}"/>
+
+      <group title="Multibinder Extension" packages="com.google.inject.multibindings"/>
       <fileset dir="${multibindings.src.dir}"/>
-      <fileset dir="${persist.src.dir}"/>
-      <fileset dir="${grapher.src.dir}"/>
+
+      <group title="ThrowingProviders Extension" packages="com.google.inject.throwingproviders"/>
+      <fileset dir="${throwingproviders.src.dir}"/>
+
+      <group title="Test Libraries Extension" packages="com.google.inject.testing.*"/>
       <fileset dir="${testlib.src.dir}"/>
-      <!-- TODO: this breaks Doclava for some reason
-      <fileset dir="${struts2.src.dir}"/> -->
 
-      <doclet name="com.google.doclava.Doclava">
-        <param name="-hdf"/> <param name="project.name"/> <param name="Guice"/>
-        <param name="-since"/> <param name="lib/build/guice-1.0.xml"/> <param name="Guice_1.0" />
-        <param name="-since"/> <param name="lib/build/guice-2.0.xml"/> <param name="Guice_2.0" />
-        <param name="-since"/> <param name="lib/build/guice-3.0.xml"/> <param name="Guice_3.0" />
-        <param name="-apiversion" value="Guice_${new.api}"/>
-        <param name="-assetsdir" value="javadoc/assets"/>
-        <param name="-apixml" value="build/docs/guice-${new.api}.xml"/>
-        <!-- TODO: fix doclava federation
-          http://aopalliance.sourceforge.net/doc
-          http://www.springframework.org/docs/api/
-          <param name="-federate"/><param name="JDK"/><param name="http://download.oracle.com/javase/6/docs/api/index.html?"/>
-          <param name="-federationxml"/><param name="JDK"/><param name="http://doclava.googlecode.com/svn/static/api/openjdk-6.xml"/>
-        -->
-      </doclet>
+      <group title="Grapher Extension" packages="com.google.inject.grapher:com.google.inject.grapher.*"/>
+      <fileset dir="${grapher.src.dir}"/>
+
+      <group title="Persist Extension" packages="com.google.inject.persist:com.google.inject.persist.*"/>
+      <fileset dir="${persist.src.dir}"/>
+
+      <group title="Spring Extension" packages="com.google.inject.spring"/>
+      <fileset dir="${spring.src.dir}"/>
+
+      <group title="Struts2 Extension" packages="com.google.inject.struts2"/>
+      <fileset dir="${struts2.src.dir}"/> 
+
+      <group title="JNDI Extension" packages="com.google.inject.jndi"/>     
+      <fileset dir="${jndi.src.dir}"/>
+
+      <group title="JMX Extension" packages="com.google.inject.tools.jmx"/>
+      <fileset dir="${jmx.src.dir}"/>      
+
+      <link href="http://aopalliance.sourceforge.net/doc/"/>
+      <link href="http://docs.oracle.com/javase/7/docs/api/"/>
+      <link href="http://atinject.googlecode.com/svn/trunk/javadoc/"/>
+      <link href="http://docs.guava-libraries.googlecode.com/git/javadoc/"/>
+      <link href="https://tomcat.apache.org/tomcat-5.5-doc/servletapi/"/>
     </javadoc>
-    <move todir="build/docs/javadoc"><fileset dir="build/docs/reference"/></move>
   </target>
 
   <target name="no_aop"

diff --git a/core/src/com/google/inject/spi/ElementSource.java b/core/src/com/google/inject/spi/ElementSource.java
@@ -8,29 +8,36 @@
 import java.util.List;
 
 /**
- * Contains information about where and how an {@link Element element} was bound.
- * <p> 
- * The {@link #getDeclaringSource() declaring source} refers to a location in source code that 
- * defines the Guice {@link Element element}. For example, if the element is created from a method
- * annotated by {@literal @Provides}, the declaring source of element would be the method itself. 
+ * Contains information about where and how an {@link Element element} was
+ * bound.
  * <p>
- * The {@link #getStackTrace()} refers to the sequence of calls ends at one of {@link Binder} 
- * {@code bindXXX()} methods and eventually defines the element. Note that {@link #getStackTrace()} 
- * lists {@link StackTraceElement StackTraceElements} in reverse chronological order. The first 
- * element (index zero) is the last method call and the last element is the first method invocation.
- * By default, the stack trace is not collected. The default behavior can be changed by setting the 
- * {@code guice_include_stack_traces} flag value. The value can be either {@code OFF}, {@code
- * ONLY_FOR_DECLARING_SOURCE} or {@code COMPLETE}. Note that collecting stack traces for every
- * binding can cause a performance hit when the injector is created.
+ * The {@link #getDeclaringSource() declaring source} refers to a location in
+ * source code that defines the Guice {@link Element element}. For example, if
+ * the element is created from a method annotated by {@literal @Provides}, the
+ * declaring source of element would be the method itself.
  * <p>
- * The sequence of class names of {@link Module modules} involved in the element creation can be 
- * retrieved by {@link #getModuleClassNames()}. Similar to {@link #getStackTrace()}, the order is 
- * reverse chronological. The first module (index 0) is the module that installs the {@link Element 
- * element}. The last module is the root module.
+ * The {@link #getStackTrace()} refers to the sequence of calls ends at one of
+ * {@link com.google.inject.Binder} {@code bindXXX()} methods and eventually
+ * defines the element. Note that {@link #getStackTrace()} lists
+ * {@link StackTraceElement StackTraceElements} in reverse chronological order.
+ * The first element (index zero) is the last method call and the last element
+ * is the first method invocation. By default, the stack trace is not collected.
+ * The default behavior can be changed by setting the
+ * {@code guice_include_stack_traces} flag value. The value can be either
+ * {@code OFF}, {@code ONLY_FOR_DECLARING_SOURCE} or {@code COMPLETE}. Note that
+ * collecting stack traces for every binding can cause a performance hit when
+ * the injector is created.
  * <p>
- * In order to support the cases where a Guice {@link Element element} is created from another
- * Guice {@link Element element} (original) (e.g., by {@link Element#applyTo()}), it also
- * provides a reference to the original element source ({@link #getOriginalElementSource()}).
+ * The sequence of class names of {@link com.google.inject.Module modules}
+ * involved in the element creation can be retrieved by
+ * {@link #getModuleClassNames()}. Similar to {@link #getStackTrace()}, the
+ * order is reverse chronological. The first module (index 0) is the module that
+ * installs the {@link Element element}. The last module is the root module.
+ * <p>
+ * In order to support the cases where a Guice {@link Element element} is
+ * created from another Guice {@link Element element} (original) (e.g., by
+ * {@link Element#applyTo}), it also provides a reference to the original
+ * element source ({@link #getOriginalElementSource()}).
  */
 public final class ElementSource {
 
@@ -87,8 +94,9 @@ public ElementSource getOriginalElementSource() {
 
   /**
    * Returns a single location in source code that defines the element. It can be any object
-   * such as {@link Constructor}, {@link Method}, {@link Field}, {@link StackTraceElement}, etc. For
-   * example, if the element is created from a method annotated by {@literal @Provides}, the 
+   * such as {@link java.lang.reflect.Constructor}, {@link java.lang.reflect.Method},
+   * {@link java.lang.reflect.Field}, {@link StackTraceElement}, etc. For
+   * example, if the element is created from a method annotated by {@literal @Provides}, the
    * declaring source of element would be the method itself.
    */
   public Object getDeclaringSource() {
@@ -105,9 +113,9 @@ public List<String> getModuleClassNames() {
   }
 
   /**
-   * Returns the position of {@link Module#configure(Binder) configure(Binder)} method call in the
-   * {@link #getStackTrace() stack trace} for modules that their classes returned by
-   * {@link #getModuleClassNames()}. For example, if the stack trace looks like the following:
+   * Returns the position of {@link com.google.inject.Module#configure configure(Binder)} method
+   * call in the {@link #getStackTrace stack trace} for modules that their classes returned by
+   * {@link #getModuleClassNames}. For example, if the stack trace looks like the following:
    * <p>
    * {@code
    *  0 - Binder.bind(),
@@ -137,12 +145,12 @@ public List<Integer> getModuleConfigurePositionsInStackTrace() {
   }
 
   /**
-   * Returns the sequence of method calls that ends at one of {@link Binder} {@code bindXXX()} 
-   * methods and eventually defines the element. Note that {@link #getStackTrace()} lists {@link 
-   * StackTraceElement StackTraceElements} in reverse chronological order. The first element (index 
-   * zero) is the last method call and the last element is the first method invocation. In the cases
-   * where stack trace is not available (i.e.,the stack trace was not collected), it returns an 
-   * empty array.
+   * Returns the sequence of method calls that ends at one of {@link com.google.inject.Binder}
+   * {@code bindXXX()} methods and eventually defines the element. Note that
+   * {@link #getStackTrace} lists {@link StackTraceElement StackTraceElements} in reverse
+   * chronological order. The first element (index zero) is the last method call and the last
+   * element is the first method invocation. In the cases where stack trace is not available
+   * (i.e.,the stack trace was not collected), it returns an empty array.
    */
   public StackTraceElement[] getStackTrace() {
     int modulesCallStackSize = moduleSource.getStackTraceSize();

diff --git a/extensions/grapher/src/com/google/inject/grapher/ImplementationNode.java b/extensions/grapher/src/com/google/inject/grapher/ImplementationNode.java
@@ -21,8 +21,9 @@
 import java.util.Collection;
 
 /**
- * Node for types that have {@link Dependency}s and are bound to {@link InterfaceNode}s. These
- * nodes will often have fields for {@link Member}s that are {@link InjectionPoint}s.
+ * Node for types that have {@link com.google.inject.spi.Dependency}s and are
+ * bound to {@link InterfaceNode}s. These nodes will often have fields for
+ * {@link Member}s that are {@link com.google.inject.spi.InjectionPoint}s.
  *
  * @see DependencyEdge
  *

diff --git a/extensions/grapher/src/com/google/inject/grapher/NameFactory.java b/extensions/grapher/src/com/google/inject/grapher/NameFactory.java
@@ -22,7 +22,8 @@
 
 /**
  * Interface for a service that provides nice {@link String}s that we can
- * display in the graph for the types that come up in {@link Binding}s.
+ * display in the graph for the types that come up in
+ * {@link com.google.inject.Binding}s.
  *
  * @author [email protected] (Pete Hopkins)
  */

diff --git a/extensions/grapher/src/com/google/inject/grapher/TransitiveDependencyVisitor.java b/extensions/grapher/src/com/google/inject/grapher/TransitiveDependencyVisitor.java
@@ -35,10 +35,10 @@
 import java.util.Set;
 
 /**
- * {@link BindingTargetVisitor} that returns a {@link Collection} of the
- * {@link Key}s of each {@link Binding}'s dependencies. Used by
- * {@link InjectorGrapher} to walk the dependency graph from a starting set of
- * {@link Binding}s.
+ * {@link com.google.inject.spi.BindingTargetVisitor} that returns a
+ * {@link Collection} of the {@link Key}s of each {@link Binding}'s
+ * dependencies. Used by {@link InjectorGrapher} to walk the dependency graph
+ * from a starting set of {@link Binding}s.
  *
  * @author [email protected] (Pete Hopkins)
  */

diff --git a/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizGrapher.java b/extensions/grapher/src/com/google/inject/grapher/graphviz/GraphvizGrapher.java
@@ -38,8 +38,8 @@
 import java.util.Map.Entry;
 
 /**
- * {@link InjectorGrapher} implementation that writes out a Graphviz DOT file of the graph.
- * Dependencies are bound in {@link GraphvizModule}.
+ * {@link com.google.inject.grapher.InjectorGrapher} implementation that writes out a Graphviz DOT
+ * file of the graph. Dependencies are bound in {@link GraphvizModule}.
  * <p>
  * Specify the {@link PrintWriter} to output to with {@link #setOut(PrintWriter)}.
  *

diff --git a/extensions/grapher/src/com/google/inject/grapher/graphviz/PortIdFactory.java b/extensions/grapher/src/com/google/inject/grapher/graphviz/PortIdFactory.java
@@ -20,7 +20,7 @@
 
 /**
  * Interface for a service that returns Graphviz port IDs, used for naming the
- * rows in {@link ImplementationNode}-displaying {@link GraphvizNode}s.
+ * rows in {@link com.google.inject.grapher.ImplementationNode}-displaying {@link GraphvizNode}s.
  *
  * @author [email protected] (Pete Hopkins)
  */

diff --git a/extensions/struts2/src/com/google/inject/struts2/GuiceObjectFactory.java b/extensions/struts2/src/com/google/inject/struts2/GuiceObjectFactory.java
@@ -40,7 +40,7 @@
 import java.util.logging.Logger;
 
 /**
- * @deprecated Use {@link com.google.inject.servlet.Struts2Factory} instead.
+ * @deprecated Use {@link com.google.inject.struts2.Struts2Factory} instead.
  */
 @Deprecated
 public class GuiceObjectFactory extends ObjectFactory {

diff --git a/extensions/struts2/src/com/google/inject/struts2/Struts2GuicePluginModule.java b/extensions/struts2/src/com/google/inject/struts2/Struts2GuicePluginModule.java
@@ -19,17 +19,16 @@
 import com.google.inject.AbstractModule;
 
 /**
- * Initializes the Struts 2 Guice Plugin.
- * Must be added to the injector returned by
- *     {@link GuiceServletContextListener.getInjector()}.
+ * Initializes the Struts 2 Guice Plugin. Must be added to the injector returned
+ * by {@link com.google.inject.servlet.GuiceServletContextListener#getInjector}.
  *
  * @author benmccann.com
  */
 public class Struts2GuicePluginModule extends AbstractModule {
 
-  @Override
-  protected void configure() {
-    requestStaticInjection(Struts2Factory.class); 
-  }
+	@Override
+	protected void configure() {
+		requestStaticInjection(Struts2Factory.class);
+	}
 
 }
diff --git a/extensions/testlib/src/com/google/inject/testing/fieldbinder/BoundFieldModule.java b/extensions/testlib/src/com/google/inject/testing/fieldbinder/BoundFieldModule.java
@@ -52,10 +52,11 @@
  * {@link Bind#to} instead of the field's actual type.
  * </li>
  * <li>
- * If a {@link BindingAnnotation} or {@link Qualifier} is present on the field, that field will be
- * bound using that annotation via {@link AnnotatedBindingBuilder#annotatedWith}. For example,
- * {@code bind(Foo.class).annotatedWith(BarAnnotation.class).toInstance(theValue)}. It is an error
- * to supply more than one {@link BindingAnnotation} or {@link Qualifier}.
+ * If a {@link BindingAnnotation} or {@link javax.inject.Qualifier} is present on the field,
+ * that field will be bound using that annotation via {@link AnnotatedBindingBuilder#annotatedWith}.
+ * For example, {@code bind(Foo.class).annotatedWith(BarAnnotation.class).toInstance(theValue)}.
+ * It is an error to supply more than one {@link BindingAnnotation} or
+ * {@link javax.inject.Qualifier}.
  * </li>
  * <li>
  * If the field is of type {@link Provider}, the field's value will be bound as a {@link Provider}

diff --git a/extensions/throwingproviders/src/com/google/inject/throwingproviders/CheckedProvides.java b/extensions/throwingproviders/src/com/google/inject/throwingproviders/CheckedProvides.java
@@ -24,11 +24,11 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotates methods of a {@link Module} to create a {@link CheckedProvider}
- * method binding that can throw exceptions. The method's return type is bound
- * to a {@link CheckedProvider} that can be injected. Guice will pass
- * dependencies to the method as parameters. Install {@literal @}CheckedProvides
- * methods by using
+ * Annotates methods of a {@link com.google.inject.Module} to create a
+ * {@link CheckedProvider} method binding that can throw exceptions. The
+ * method's return type is bound to a {@link CheckedProvider} that can be
+ * injected. Guice will pass dependencies to the method as parameters. Install
+ * {@literal @}CheckedProvides methods by using
  * {@link ThrowingProviderBinder#forModule(com.google.inject.Module)} on the
  * module where the methods are declared.
  * 

diff --git a/lib/build/doclava.jar b/lib/build/doclava.jar
diff --git a/pom.xml b/pom.xml
@@ -294,6 +294,9 @@ See the Apache License Version 2.0 for the specific language governing permissio
         </plugin>
         <plugin>
           <artifactId>maven-javadoc-plugin</artifactId>
+          <configuration>
+            <additionalparam>-Xdoclint:none</additionalparam>
+          </configuration>
           <version>2.7</version>
           <executions>
             <execution>