mike rodent mike rodent - 3 months ago 32
Java Question

Ignore minor errors using javadoc

I'm trying to generate the documentation, using javadoc, from one or two downloaded jar files (with the source of course, after having extracted everything).

But using javadoc, even in an Ant file, I'm being prevented from generating this because of silly things, specifically "package XXX does not exist" and "cannot find symbol"... I just want javadoc to put the text of these things (external references) in the html docs, but to document all the .java files it finds...

NB for anyone interested this is the download page with the download files (containing source) from which I'm trying to generate the API documentation: http://logback.qos.ch/download.html

Following Mark Rotteveel's help, my Ant build file now looks like this:

<?xml version="1.0" ?>
<project name="document logback core" default="doc">
<target name="doc">
<mkdir dir="javadoc" />
<property name="excludedPackages"
value="org.codehaus.*,javax.mail.*"/>
<javadoc destdir="javadoc" sourcepath="src" packagenames="main.*"
excludepackagenames="${excludedPackages}"
additionalparam="-Xdoclint:none" />
</target>
</project>


... but it still gives errors 1) about packages not being found, including "org.codehaus.[xxx...]" and "javax.mail.[xxx...]" and 2) about symbols not being found (although this may go away if I can solve the missing packages errors).

NB the build is said to be successful, but I get complaints about no source files being found (where there are indeed commented .java files), and no html at all is generated under \javadoc.

later, following Tony Pierce's success in generating these docs

Installed Ant 1.9.6, changed path accordingly, checked to make sure this was the version being used... tried again. Failed again. This was the end of my output:


[javadoc]
D:\Desktop\Downloads\logback-1.1.7.tar\logback-1.1.7\logback-core\src\test\java\ch\qos\logback\core\appender\ConsoleAppenderTest.java:32:
error: package org.junit does not exist
[javadoc] import static
org.junit.Assert.assertEquals;
[javadoc]_______________________^


[javadoc] javadoc: error - No public or protected classes found to
document.
[javadoc] 1 error
[javadoc] 100 warnings



BUILD SUCCESSFUL Total time: 2 seconds


It does create the javadoc folder... but this is empty.

NB about the above "package does not exist" error (there were many others): this one is particularly mystifying as I thought Ant somehow included junit by default (NB I am a complete newbie at Ant, just working through "Ant in Action").

But... with the Ant
javac
task you can set
includeAntRuntime="true"
... according to this book that makes Ant's own
junit.jar
be included. Unfortunately the
javadoc
task doesn't support this attribute.

Answer

cracked it. Hopefully this approach will work for any .jar file with source from which one wants to produce the API docs.

I was only glimpsing at Ant, more or less aware that Gradle is the way to go. Now with my first faltering steps in Gradle I came up with:

Make the following build.gradle file (placed in the same directory as \src or /src, depending on platform):

apply plugin: 'java'

repositories {
    mavenCentral()
}

dependencies {
    // these mentioned as being dependencies on the logback dependencies page, see below
    compile 'org.codehaus.janino:janino:2.7.8'
    compile 'javax.mail:javax.mail-api:1.4.4'
    compile 'javax.activation:activation:1.1'

    // this one not mentioned on the logback page
    compile 'javax.servlet:servlet-api:3.0-alpha-1' 
}

Then you just go (in the same directory)

$ gradle javadoc

I'm a novice with build tools, as I said. I obtained info about the needed dependencies for the logback core from this page: http://logback.qos.ch/dependencies.html - then I explored the Maven repository a bit and found the way to specify the first three.

... but even with this I was still getting errors, so I went back to Maven Repo again and found javax.servlet. No doubt as a general principle you can in fact work out the necessary dependencies from the error messages.

AND... even after that I got lots of error/warning messages, telling me things like

warning: no @param for eventList

... but, hooray, it produced the API documentation. There's probably a javadoc switch to suppress these warnings (see discussion here).

Conclusion
I remain puzzled why you need to have these dependencies in order to produce the mere API documentation. Apparently it has something to do with the "lifecycle" of a build tool, meaning that Gradle can only carry out a task like javadoc after it has cleared a stage of configuration.

Comments