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.
diff --git a/build.xml b/build.xml
index a0f117a..95bbf1b 100644
--- 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 dir="${servlet.src.dir}"/>
- <fileset dir="${spring.src.dir}"/>
- <fileset dir="${assistedinject.src.dir}"/>
- <fileset dir="${jmx.src.dir}"/>
- <fileset dir="${jndi.src.dir}"/>
- <fileset dir="${throwingproviders.src.dir}"/>
- <fileset dir="${multibindings.src.dir}"/>
- <fileset dir="${persist.src.dir}"/>
- <fileset dir="${grapher.src.dir}"/>
- <fileset dir="${testlib.src.dir}"/>
- <!-- TODO: this breaks Doclava for some reason
- <fileset dir="${struts2.src.dir}"/> -->
+ </fileset>
- <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="Servlet Extension" packages="com.google.inject.servlet"/>
+ <fileset dir="${servlet.src.dir}"/>
+
+ <group title="AssistedInject Extension" packages="com.google.inject.assistedinject"/>
+ <fileset dir="${assistedinject.src.dir}"/>
+
+ <group title="Multibinder Extension" packages="com.google.inject.multibindings"/>
+ <fileset dir="${multibindings.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}"/>
+
+ <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
index 35246d4..3c1837c 100644
--- 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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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
index b4a67a0..f85fc96 100644
--- 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
index 4cd7fa6..20e740a 100644
--- 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 phopkins@gmail.com (Pete Hopkins)
*/
diff --git a/extensions/grapher/src/com/google/inject/grapher/TransitiveDependencyVisitor.java b/extensions/grapher/src/com/google/inject/grapher/TransitiveDependencyVisitor.java
index 51ba1cc..b72e876 100644
--- 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 phopkins@gmail.com (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
index 4a312c3..ff8f8b5 100644
--- 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
index bc5deda..1883fc8 100644
--- 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 phopkins@gmail.com (Pete Hopkins)
*/
diff --git a/extensions/struts2/src/com/google/inject/struts2/GuiceObjectFactory.java b/extensions/struts2/src/com/google/inject/struts2/GuiceObjectFactory.java
index f3bf8f0..4d7c485 100644
--- 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
index 5356afe..00291af 100644
--- 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
index 5d98b0a..7943e89 100644
--- 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
index 3257d28..b702dcc 100644
--- 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
deleted file mode 100644
index 6abed4b..0000000
--- a/lib/build/doclava.jar
+++ /dev/null
Binary files differ
diff --git a/pom.xml b/pom.xml
index 9f63317..567904e 100644
--- a/pom.xml
+++ b/pom.xml
@@ -294,6 +294,9 @@
</plugin>
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
+ <configuration>
+ <additionalparam>-Xdoclint:none</additionalparam>
+ </configuration>
<version>2.7</version>
<executions>
<execution>