Merge pull request #822 from sameb/no-doclava
Cleanup javadocs, stop using doclava
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..a20ee53 100644
--- a/extensions/struts2/src/com/google/inject/struts2/Struts2GuicePluginModule.java
+++ b/extensions/struts2/src/com/google/inject/struts2/Struts2GuicePluginModule.java
@@ -19,9 +19,8 @@
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
*/
@@ -29,7 +28,7 @@
@Override
protected void configure() {
- requestStaticInjection(Struts2Factory.class);
+ 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/generate-latest-docs.sh b/generate-latest-docs.sh
index aea4d81..683c5fd 100755
--- a/generate-latest-docs.sh
+++ b/generate-latest-docs.sh
@@ -1,7 +1,7 @@
# see http://benlimmer.com/2013/12/26/automatically-publish-javadoc-to-gh-pages-with-travis-ci/ for details
if [ "$TRAVIS_REPO_SLUG" == "google/guice" ] && \
- [ "$TRAVIS_JDK_VERSION" == "oraclejdk7" ] && \
+ [ "$TRAVIS_JDK_VERSION" == "oraclejdk8" ] && \
[ "$LABEL" == "ant" ] && \
[ "$TRAVIS_PULL_REQUEST" == "false" ] && \
[ "$TRAVIS_BRANCH" == "master" ]; then
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>