roycezhc / doclava Goto Github PK

Please, consider implementing -link command line argument like the standard 
doclet does [1]

[1] 
<http://download.oracle.com/javase/1.5.0/docs/tooldocs/solaris/javadoc.html#link
>

What steps will reproduce the problem?
1. Create a Maven project using GWT 2.0.3 as a dependancy.
2. Use mvn javadoc:javadoc.
3. Javadoc fails with the following output:

[ERROR] Failed to execute goal 
org.apache.maven.plugins:maven-javadoc-plugin:2.8:aggregate (default-cli) on 
project ***: An error has occurred in JavaDocs report generation:
[ERROR] Exit code: 1 - javadoc: error - In doclet class 
com.google.doclava.Doclava,  method start has thrown an exception 
java.lang.reflect.InvocationTargetException
[ERROR] com.sun.tools.javac.code.Symbol$CompletionFailure: class file for 
com.google.gwt.core.ext.TreeLogger not found

The class file is actually missing, Eclipse does not find it. The following 
configuration gives the above output:
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.8</version>
                <configuration>
                    <docletArtifact>
                        <groupId>com.google.doclava</groupId>
                        <artifactId>doclava</artifactId>
                        <version>1.0.3</version>
                    </docletArtifact>
                    <doclet>com.google.doclava.Doclava</doclet>
                    <useStandardDocletOptions>false</useStandardDocletOptions>
                    <!-- | bootclasspath required by Sun's JVM -->
                    <bootclasspath>${sun.boot.class.path}</bootclasspath>
                    <additionalparam>
                        -quiet
                        -d ${project.reporting.outputDirectory}/apidocs
                        -hdf project.name "${project.name}"
                    </additionalparam>
                    <!-- | Apple's JVM sometimes requires more memory -->
                    <additionalJOption>-J-Xmx1024m</additionalJOption>
                </configuration>
            </plugin>

But switching it to the following works and generates a full Javadoc:

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.8</version>
                <configuration>
                    <!-- | bootclasspath required by Sun's JVM -->
                    <bootclasspath>${sun.boot.class.path}</bootclasspath>
                    <additionalparam>
                        -quiet
                        -d ${project.reporting.outputDirectory}/apidocs
                    </additionalparam>
                    <!-- | Apple's JVM sometimes requires more memory -->
                    <additionalJOption>-J-Xmx1024m</additionalJOption>
                </configuration>
            </plugin>

(running on Windows XP SP3)

As reported as internal issue 2752081 by enh,

We've been writing "On Android" in our documentation, but that's going to look 
stupid for other projects. it would be good if we could supply something like 
-DPLATFORM=Android to doclava and then have it replace ${PLATFORM} (or 
whatever) with the given text.

in http://developer.android.com/reference/java/util/Locale.html, "Locale data" 
is blue but "Be wary of the default locale" is black.

in the Java source they're the same:

 * <a name="locale_data"><h3>Locale data</h3></a>

 * <a name="default_locale"><h3>Be wary of the default locale</h3></a>

but it looks from the webkit inspector like droiddoc mangles them so "Locale 
data" is "h3 > a" but the other is "a > h3". and the CSS only works for one of 
those orderings.

this line should end "</th>"...

./res/assets/templates/macros.cs:197:            <th><?cs 
call:type_link(tag.type) ?></td>

URLs produced by Doclava aren't compliant URLs.  They contain a number of 
invalid characters for a URI, including '<', '>' and '?'.  The main problem is 
that the URLs are including generic types whereas the JDK javadoc does not.

For an example, this method:
 Binder.bindInterceptor(Matcher<? super Class<?>> classMatcher, Matcher<? super Method> methodMatcher, MethodInterceptor... interceptors)
 produces an href of:
 href="../../../com/google/inject/Binder.html#bindInterceptor(com.google.inject.matcher.Matcher<? super java.lang.Class<?>>, com.google.inject.matcher.Matcher<? super java.lang.reflect.Method>, org.aopalliance.intercept.MethodInterceptor...)"

Whereas in the JDK javadoc, the method:
 Map.putAll(Map<? extends K,? extends V> m) 
produces an href of:
 HREF="../../java/util/Map.html#putAll(java.util.Map)"

doclava dies on a particular class, org.apache.felix.framework.ServiceRegistry.

What steps will reproduce the problem?
1. Unzip the attached Maven project 
2. Run 'mvn javadoc:javadoc'
3. Have a sad :(

What is the expected output? What do you see instead?
The error is:

Exit code: 1 - javadoc: error - In doclet class com.google.doclava.Doclava,  
method start has thrown an exception java.lang.reflect.InvocationTargetException
java.lang.NullPointerException
    at com.sun.tools.javadoc.ClassDocImpl.getClassName(ClassDocImpl.java:341)
    at com.sun.tools.javadoc.ClassDocImpl.qualifiedName(ClassDocImpl.java:298)
    at com.google.doclava.ProjectBuilder.docToInfo(ProjectBuilder.java:288)
    at com.google.doclava.ProjectBuilder.obtainClass(ProjectBuilder.java:274)
    at com.google.doclava.ProjectBuilder.convertClasses(ProjectBuilder.java:218)
    at com.google.doclava.ProjectBuilder.initClass(ProjectBuilder.java:157)
    at com.google.doclava.ProjectBuilder.build(ProjectBuilder.java:70)
    at com.google.doclava.Doclava.start(Doclava.java:246)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
    at java.lang.reflect.Method.invoke(Method.java:597)
    at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
    at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
    at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
    at com.sun.tools.javadoc.Start.begin(Start.java:128)
    at com.sun.tools.javadoc.Main.execute(Main.java:41)
    at com.sun.tools.javadoc.Main.main(Main.java:31)

What version of the product are you using? On what operating system?
This happens on doclava 1.0.3 and later.

Ubuntu 11.04 (also confirmed on OS X 10.7)

$ java -version
java version "1.6.0_26"
Java(TM) SE Runtime Environment (build 1.6.0_26-b03)
Java HotSpot(TM) 64-Bit Server VM (build 20.1-b02, mixed mode)

Please provide any additional information below.

Debugging reveals com.google.doclava.Converter, line 86 as the problem:

cl.init3(Converter.convertTypes(c.typeParameters()), 
Converter.convertClasses(c.innerClasses(false)));

When ServiceRegistry hits this line, c.innerClasses(false) returns at first 
three inner class references, one of which is null. Dereferencing that null 
causes the problem. If I call c.innerClasses(false) *twice*, the first call 
returns the three inner class refs (including the null one), while the second 
call returns two valid inner class refs and the program goes happily on its way.

As the standard doclet has no trouble with this class, I assume it's something 
wrong in doclava, but I don't know what. 

It's also worth mentioning that on Oracle's Java 7, this problem is not extant 
-- c.innerClasses(false) returns only the two valid inner class references.

1. i want to write something like:

---CODE---
 for (int i = 0; i < bytes.length; ++i) {
 }
---CODE---

without having to worry about spacing or blank lines or PREs and @codes or < or 
> and so forth.

2. i want to be able to *compile* samples.

2a. i want to have the surrounding code inferred:

---CODE---
System.err.println(Locale.getAvailableLocales());
---CODE---
becomes
import java.util.Locale;
public final class Sample0001 {
 public static void main(String[] _) {
  System.err.println(Locale.getAvailableLocales());
 }
}

2b. i want to be able to supply [some of] the surrounding code:

---CODE---
!void hexdump(byte[] bytes) {
! ...
!}
hexdump("hello".getBytes("UTF-8"));
---CODE---

3. i want to be able to *run* samples. specifically, i want an expression style 
that includes the output in the HTML:

---LIVE-EXPRESSION---
Locale.getAvailableLocales()
---LIVE-EXPRESSION---
inserts "[ar, ca, de, ...]" in the HTML.


see also rubydoc/ri.

What steps will reproduce the problem?
1. generate javadoc for jdk 1.5 source
2. fails with a NPE on ClassInfo line 1043 (attempting to iterate over a null 
list)
3. this is caused when a ClassInfo object is instantiated via the reflection 
API; the mEnumConstants member is never assigned a value

To patch this, change line 1143 of ClassInfo.java to:

private List<FieldInfo> mEnumConstants = new ArrayList<FieldInfo>();

See Formatter.
http://developer.android.com/reference/java/util/Formatter.html

It generates the correct documentation with Javadoc.

What steps will reproduce the problem?
1. Add a comment with a tag: {@code hello {world}!}

What is the expected output? What do you see instead?
<code>hello {world}!}</code>
vs.
<code>hello {world</code>!}

As reported as internal issue 2894577 by bdc,

For example, when the Array.newInstance dimensions parameter changed from int[] 
to int it should not be reported as an API change.

bjdodson recommends flagging this type of API change with a new error 
CHANGED_VARARGS, with default level HIDDEN.

This is a patch to add support for a -templatezip parameter. Given a zip file, 
it treats the contents as a -templatedir, loading the unzipped files from a 
temp directory and cleaning up after itself afterwards.

We find this useful because we keep our doclava templates in a maven artifact 
and this saves us the pain of writing maven configuration in the POM to handle 
the unzip.

As reported as internal issue 2894586 by bdc,

Doclava is a bit too terse reporting method names, only printing the name 
without the signature. It would be nice if there are overloaded methods that it 
would print the signature for the user to disambiguate which method is the 
problem. I think people would prefer to keep the shorter output when there the 
method name on its own is non-ambiguous.

even worse, it seems to try to help by eliding the multiple problems with 
different overloaded methods/constructors into on error.

the gingerbread HttpURLConnection docs don't look as good as they should.

1. there's a missing } that appears in the source but not in the HTML:

      readStream(in);
!    finally {
      urlConnection.disconnect();

2. there are missing gaps between paragraphs and the following PRE. (the 
"Network Sign-On" code sample, say.)

3. there are trailing blank lines in PREs. (the "Performance" code sample, say.)


as far as i can tell, the .java is fine; it bends over backwards to do the 
right thing, even though it's a PITA. this bug isn't asking for a better input 
format --- this bug is just asking for doclava to do the right thing with 
regular javadoc-style input.

See 
http://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/Injector.
html#getProvider%28com.google.inject.Key%3CT%3E%29 for an example.  The javadoc 
just says: 
-- 
See Also
    * for an alternative that offers up front error detection
--
(where 'for an ...' is a link), but it really should show 'Binder.getProvider' 
as the link & 'for an ...' as a non-linked description, like how Throws works.

The guice docs are currently here:
  http://google-guice.googlecode.com/svn/trunk/javadoc/

Using Doclava requires me to move them one level deeper, to here:
  http://google-guice.googlecode.com/svn/trunk/javadoc/reference

This is annoying because to keep my current URLs like this:
  http://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/Injector.html
I need to include 'assets' in the top-level directory.

As reported as internal issue 2895274 by bdc,

Sometimes doclava helps by saying what the change was (although note the bug 
here because of the empty string hard to read):
(unknown): warning 19: Class 
java.util.concurrent.locks.AbstractOwnableSynchronizer scope changed from  to 
public

however for abstract (and I think some other) changes, it doesn't say if its 
going from true to false or false to true. Seems like it should:

(unknown): warning 20: Class java.text.CollationKey changed abstract qualifier
(unknown): warning 20: Method java.text.CollationKey.compareTo has changed 
'abstract' qualifier
(unknown): warning 20: Method java.text.CollationKey.toByteArray has changed 
'abstract' qualifier

Also note the inconsistent messages, the method one has '...' around abstract, 
the class case does not...

We're missing the annotation method value() for Named here:
http://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/name/Name
d.html

Maven allows doclets to be specified as an artifact. Deploying Doclava to the 
public Maven repository would allow developers to use Doclava with simple 
cut-and-paste configuration, and no extra download.

http://maven.apache.org/plugins/maven-javadoc-plugin/examples/alternate-doclet.h
tml

What steps will reproduce the problem?
1. Add the Maven pom.xml like in the Wiki Instructions
2. Run mvn site

What is the expected output? What do you see instead?

Site documentation is generated.  However this only appears if mvn 
javadoc:javadoc is run and mvn site reverts to the normal Javadoc.

I tried moving it to the <reporting> section of the pom.xml but the site is not 
built correctly.  Would prefer to have doclava built with my site goal!

Apache Maven 2.2.1 (r801777; 2009-08-06 15:16:01-0400)
Java version: 1.6.0_18
Java home: C:\Program Files (x86)\Java\jdk1.6.0_18\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 7" version: "6.1" arch: "x86" Family: "windows"

POM file attached for viewing.

The doclava 1.0.5 plugin artifacts do not appear to have been deployed to Maven 
Central (previous release have been).

I think this is desirable for wider use.

What steps will reproduce the problem?
1. Add a reference to {@link Iterable}
2. Federate documentation with something providing Iterable

What is the expected output? What do you see instead?
Link to remote description. Currently, we link to an invalid page.

What steps will reproduce the problem?
1. Create class extending from federated project (e.g. CustomView extends View 
in android)
2. add @see tag in JavaDoc (e.g. @see TypedValue#COMPLEX_UNIT_PT)
3. generate documentation

What is the expected output? What do you see instead?
expected: Link to federated project in "See Also"
actual: Link to non existent page (/reference/null#COMPLEX_UNIT_PT)

> What steps will reproduce the problem?
1.  svn co http://doclava.googlecode.com/svn/trunk/ doclava (@ r325)
2. mvn install


> What is the expected output? 

All tests pass.

What do you see instead?

Running doclava.ApiCheckTest
Tests run: 49, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.751 sec <<< 
FAILURE!
Running doclava.FloatingPointToStringTest
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.024 sec

Results :

Failed tests: 
  testChangedSynchronized(doclava.ApiCheckTest)


[building from source to pull in the code from 
http://code.google.com/p/doclava/source/detail?r=318, as I'm getting a NPE when 
generating docs]

run doclava against javadoc that references {@link SomeEnum#value()} and see:
  warning 101: Unresolved link/see tag "SomeEnum#value()"

running @r325

Example (valueOf and values for Enums): 
https://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/Stage.ht
ml

Once JSilver will be deployed in the Maven Central repository 
(http://code.google.com/p/jsilver/issues/detail?id=1) the Doclava build/deploy 
can benefit as well of such improvement, so jsilver jar doesn't need anymore to 
be imported and installed locally.

The attached patch contains the improvement for the pom and has to be applied 
only after jsilver will be available.
Moreover minor metadata issues have been fixed:
* the scm urls were referring to the tag instead of the trunk
* the bootclasspath is available under sun.boot.class.path property that makes 
the build portable
* the tools.jar dependency is already available in the Maven classpath, not 
needed to be imported

Feel free to ping me whenever something goes wrong.

For example, "{@literal<}V, B>" should render as "<V, B>" (that's how it works 
with Eclipse's javadoc, at least).  conversely, using "{@literal <}V, B>" (a 
space before the literal) causes Eclipse's javadoc to render " <V, B>" (with a 
space before the < -- it literally writes everything between "@literal" and 
"}", so it's not a good workaround.  (using &lt; is a valid workaround, though.)

see 
http://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/spi/Provi
derWithExtensionVisitor.html for an example.

To compliment or replace the Javadoc tag.

Feature request to have doclava generate a "deprecated since" API level number 
as an hdf var, which would then be displayed in the reference docs for 
deprecated classes/methods etc. 

Scott and I can help with the integration into the doc templates. 

Chrome doesn't support cookies in offline browsing, causing the api filter to 
break.

What steps will reproduce the problem?
1. using Maven, import Doclava in a project compiled with Java1.5
2. generate javadoc

What is the expected output? What do you see instead?

$ mvn -version
Apache Maven 3.0.1 (r1038046; 2010-11-23 11:58:32+0100)
Java version: 1.5.0_24
Java home: /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home
Default locale: en_US, platform encoding: MacRoman
OS name: "mac os x" version: "10.6.4" arch: "i386" Family: "unix"

...

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 19.303s
[INFO] Finished at: Sat Dec 04 22:13:24 CET 2010
[INFO] Final Memory: 16M/1016M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal 
org.apache.maven.plugins:maven-javadoc-plugin:2.7:jar (attach-javadocs) on 
project mybatis-guice: MavenReportException: Error while creating archive:
[ERROR] Exit code: 1 - javadoc: error - In doclet class 
com.google.doclava.Doclava,  method start has thrown an exception 
java.lang.reflect.InvocationTargetException
[ERROR] java.lang.NoSuchMethodError: java.lang.String.isEmpty()Z
[ERROR] at com.google.doclava.PackageInfo.<init>(PackageInfo.java:37)
[ERROR] at 
com.google.doclava.ProjectBuilder.obtainPackage(ProjectBuilder.java:385)
[ERROR] at com.google.doclava.ProjectBuilder.initClass(ProjectBuilder.java:157)
[ERROR] at com.google.doclava.ProjectBuilder.build(ProjectBuilder.java:70)
[ERROR] at com.google.doclava.Doclava.start(Doclava.java:246)
[ERROR] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
[ERROR] at 
sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
[ERROR] at 
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.jav
a:25)
[ERROR] at java.lang.reflect.Method.invoke(Method.java:592)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
[ERROR] at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
[ERROR] at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
[ERROR] at com.sun.tools.javadoc.Start.begin(Start.java:128)
[ERROR] at com.sun.tools.javadoc.Main.execute(Main.java:41)
[ERROR] at com.sun.tools.javadoc.Main.main(Main.java:31)



Please use labels and text to provide additional information.

I suggest to:
* replace com.google.doclava.PackageInfo line #37 with {{{ mName = 
name.length() == 0 ? DEFAULT_PACKAGE : name; }}}
* remove the catch block in com.google.doclava.JarUtils lines #78-#80

That should be enough to make Doclava retro-compatible even if compiled with 
Java6

What steps will reproduce the problem?
1. Using Java JDK 1.6 use Doclava
2. Run it

I get an error:
javadoc: error - In doclet class com.google.doclava.Doclava,  method start has 
thrown an exception java.lang.reflect.InvocationTargetException
com.sun.tools.javac.code.Symbol$CompletionFailure: class file for 
sun.util.resources.OpenListResourceBundle not found

As reported as internal issue 2739691 by enh,

[random example] AbstractInterruptibleChannel isn't a subclass of Closeable 
(http://www.corp.google.com/~dalvik-prebuild/offline-sdk/reference/java/io/Close
able.html):

java.io.Closeable
Known Indirect Subclasses
AbstractInterruptibleChannel, AbstractSelectableChannel, 
AssetFileDescriptor.AutoCloseInputStream, 
AssetFileDescriptor.AutoCloseOutputStream, AssetManager.AssetInputStream, 
BackupDataInputStream, Base64InputStream, Base64OutputStream, 
BluetoothServerSocket, BluetoothSocket, BufferedInputStream, 
BufferedOutputStream, BufferedReader, BufferedWriter, ByteArrayInputStream, 
ByteArrayOutputStream, ByteChannel, Channel, CharArrayReader, CharArrayWriter, 
CheckedInputStream, CheckedOutputStream, ChunkedInputStream, 
ChunkedOutputStream, CipherInputStream, CipherOutputStream, 
ContentLengthInputStream, ContentLengthOutputStream, DataInputStream, 
DataOutputStream, DatagramChannel, DeflaterInputStream, DeflaterOutputStream, 
DigestInputStream, DigestOutputStream, EofSensorInputStream, FileChannel, 
FileInputStream, FileOutputStream, FileReader, FileWriter, FilterInputStream, 
FilterOutputStream, FilterReader, FilterWriter, Formatter, GZIPInputStream, 
GZIPOutputStream, GatheringByteChannel, IdentityInputStream, 
IdentityOutputStream, InflaterInputStream, InflaterOutputStream, InputStream, 
InputStreamReader, InterruptibleChannel, JarInputStream, JarOutputStream, 
LineNumberInputStream, LineNumberReader, ObjectInputStream, ObjectOutputStream, 
OutputStream, OutputStreamWriter, ParcelFileDescriptor.AutoCloseInputStream, 
ParcelFileDescriptor.AutoCloseOutputStream, Pipe.SinkChannel, 
Pipe.SourceChannel, PipedInputStream, PipedOutputStream, PipedReader, 
PipedWriter, PrintStream, PrintWriter, PushbackInputStream, PushbackReader, 
RandomAccessFile, ReadableByteChannel, Reader, ScatteringByteChannel, 
SelectableChannel, SequenceInputStream, ServerSocketChannel, SocketChannel, 
StringBufferInputStream, StringReader, StringWriter, WritableByteChannel, 
Writer, ZipInputStream, ZipOutputStream


"Implemented By" would be less unreasonable.

it might also be worth having "Direct Subinterfaces" and/or "Indirect 
Subinterfaces". for example, ByteChannel really is a subinterface of 
ReadableByteChannel but FileChannel is an implementor of ReadableByteChannel, 
yet we group them together as if they're all the same 

This isn't just a grammatical nit that we could fix by using vaguer wording: 
looking for implementing classes and looking for subinterfaces are two distinct 
tasks, and the reader might reasonably be attempting to perform either of them.

It's a backwards-incompatible change to change the exceptions thrown from 
callable or overridable methods.

We're missing the annotation "Named" from the left-hand nav:
http://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/name/Name
d.html

What steps will reproduce the problem?
1. Try to federate against http://example.org/current.xml.gz

What is the expected output? What do you see instead?
Federation should work.

This saves a lot of bandwidth and compilation time. Also, cache .xml files for 
future compilation.

What steps will reproduce the problem?
1. Generate documentation for api v1
2. Add enum constants to api v2
3. Generate documentation

What is the expected output? What do you see instead?
Enum constants show "Added in v2"

javadoc sucks. we want markdown, or code.google.com wiki.

see http://developer.android.com/reference/java/util/regex/Pattern.html --- the 
documentation for toString is inherited, and the #anchor in it needs to point 
to Object.html, not Pattern.html.

Using latest trunk snapshot build:

1) Create a class with no constructor declared (so using default constructor)
2) Create an enum with some values
3) Generate doclava javadoc using the -todo todo.html

The todo.html should not contain the default constructor for the class you 
created, nor should in contain valueOf(String) or values() for the enum. The 
constructor and the enum methods are generated, so the javadoc is not missing.

Patch for fix supplied.

What steps will reproduce the problem?
1. populate a doc-files directory in the source code path
2. build with default settings, e.g. using ant

What is the expected output? What do you see instead?

The standard way to embed images in Javadoc is to create a directory named 
"doc-files".  This is used by Eclipse as well as Java's default doclet.  
Doclava doesn't copy the directory.

What version of the product are you using? On what operating system?

Docalava 1.0.5 on Mac OS X 10.6.8, Java 1.6.0_29, ant 1.8.2.

The workaround in Ant is to add a copy task to the build.

As reported as internal issue 2915165 by enh,

Given this, where the first quoted line is line 25, doclava will complain

frameworks/base/../../libcore/luni/src/main/java/java/util/TimeZone.java:25: 
error 1: Unresolved link/see tag "SimpleDateFormat" in java.util.TimeZone

though the error is actually 14 lines further on. this is confusing.

 * {@code TimeZone} represents a time zone, primarily used for configuring a {@link Calendar} or
 * {@link java.text.SimpleDateFormat} instance.
 *
 * <p>Most applications will use {@link #getDefault} which returns a {@code TimeZone} based on
 * the time zone where the program is running.
 *
 * <p>You can also get a specific {@code TimeZone} {@link #getTimeZone by id}.
 *
 * <p>It is highly unlikely you'll ever want to use anything but the factory methods yourself.
 * Let classes like {@link Calendar} and {@link SimpleDateFormat} do the date
 * computations for you.

it would be even better if we could say how many times the problem occurs, so 
i'd have known straight away that there were two instances of the same error. 
(originally, the first reference to SimpleDateFormat was also unqualified, and 
actually _was_ on line 25.)

Links within Doclava sites require a 'reference' prefix. If I upload the 
reference directory to a folder named 'javadoc' on my server, everything breaks.

Doclava fails when it tries to source the struts2 extension for Guice.  It 
prints out this exception:

javadoc: error - In doclet class com.google.doclava.Doclava,  method start has 
thrown an exception java.lang.reflect.InvocationTargetException
java.lang.ClassCastException: com.sun.tools.javadoc.ClassDocImpl cannot be cast 
to com.sun.javadoc.AnnotationTypeDoc
    at com.sun.tools.javadoc.AnnotationDescImpl.annotationType(AnnotationDescImpl.java:46)
    at com.google.doclava.ProjectBuilder.obtainAnnotationInstance(ProjectBuilder.java:486)
    at com.google.doclava.ProjectBuilder.convertAnnotationInstances(ProjectBuilder.java:475)
    at com.google.doclava.ProjectBuilder.obtainMethod(ProjectBuilder.java:343)
    at com.google.doclava.ProjectBuilder.convertMethods(ProjectBuilder.java:305)
    at com.google.doclava.ProjectBuilder.initClass(ProjectBuilder.java:157)
    at com.google.doclava.ProjectBuilder.build(ProjectBuilder.java:70)
    at com.google.doclava.Doclava.start(Doclava.java:246)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
1 error
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
100 warnings
    at java.lang.reflect.Method.invoke(Method.java:597)
    at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
    at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
    at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
    at com.sun.tools.javadoc.Start.begin(Start.java:128)
    at com.sun.tools.javadoc.Main.execute(Main.java:41)
    at com.sun.tools.javadoc.Main.main(Main.java:31)

checkout the guice code & uncomment the struts2 src in trunk/build.xml:javadoc 
(and run the javadoc target) to reproduce.

every see also link here is to a different class, but droiddoc incorrectly 
elides the class name. if the class name != the current class' name, droiddoc 
should never elide the class name.

http://developer.android.com/reference/java/util/Locale.html#getAvailableLocales
()

use css instead:

http://davidwalsh.name/nobr-css

Currently the 'since' version model allows APIs to only be added, never 
removed. This doesn't work for APIs like guice that have special limited 
versions for platforms like Android.

Doclava's version tagging should work even as features get removed.

What steps will reproduce the problem?
1. Switch to a Standard JVM
2. Try invoke the compilation
3. The compiler complains with following message:
/src/com/google/doclava/PackageInfo.java:[37,16] cannot find symbol
symbol  : method isEmpty()
location: class java.lang.String

What is the expected output? What do you see instead?
Use a standard way to perform the check, i.e. String#length() == 0

What version of the product are you using? On what operating system?
$ uname
Darwin Simone-Tripodis-MacBook-Pro.local 10.4.0 Darwin Kernel Version 10.4.0: 
Fri Apr 23 
18:28:53 PDT 2010; root:xnu-1504.7.4~1/RELEASE_I386 i386

$ java -version
java version "1.5.0_24"
Java(TM) 2 Runtime Environment, Standard Edition (build 
1.5.0_24-b02-357-10M3065)
Java HotSpot(TM) Client VM (build 1.5.0_24-149, mixed mode, sharing)

Please provide any additional information below.
The current javadoc doesn't report the isEmpty() method: 
http://download.oracle.com/javase/1.5.0/docs/api/java/lang/String.html#length()