Ignore minor errors using javadoc

Question

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.

later still

My thinking was a bit muddled on this, to be honest: the simplest way I have found to compile javadocs from third-party source jars is just by extracting and then using the command line, typically:

javadoc -d docs -Xmaxwarns 10 -Xmaxerrs 10 -Xdoclint:none -sourcepath . -subpackages ch.qos.logback.core

... as for javadoc for one's own code this doesn't seem to be a problem in Gradle (I was only glimpsing at Ant, aware that the future is Gradle... and it's not particularly difficult to get to grips with the basics).

NB If you install the Gradle STS plugin for Eclipse, and then create a new project using Gradle STS wizard your build file contains the line

apply plugin: 'eclipse'

... one of the effects of which is that by default the source as well as the executables for all your third-party dependencies will be downloaded under GRADLE_HOME during the build. Pretty good!

Answer 1

Java 8 introduced doclint which will treat certain problems as an error and not produce the documentation. It is possible to disable this by specifying the commandline option -Xdoclint:none.

See also: Turning off doclint in JDK 8 Javadoc

Eg in Ant you would need to do add a additionalparam="-Xdoclint:none" attribute to the javadoc task. A (slightly modified) example from Jaybird:

<target name="javadocs" depends="init,set-driver-sources">
    <mkdir dir="${build.docs}"/>
    <javadoc destdir="${build.docs}"
             author="true"
             version="true"
             windowtitle="${Name} API"
             doctitle="${Name}"
             extdirs="${module.thirdparty}"

             additionalparam="-Xdoclint:none"

             excludepackagenames="${excludedPackages}"
             bottom="Copyright &#169; 2001-2015 Jaybird (Firebird JDBC/JCA) team. All rights reserved.">
        <arg line="${java.module.arg}"/>
        <classpath refid="javac.driver.classpath"/>
        <sourcepath>
            <pathelement path="${source.java}"/>
            <pathelement path="${source.jna-client}"/>
        </sourcepath>
        <sourcepath refid="source.java.openoffice"/>
        <sourcepath refid="source.java.additional"/>
        <link href="http://docs.oracle.com/javase/7/docs/api/"/>
    </javadoc>
</target>

Answer 2

Compile Errors With Custom Doclet with Java 9 or later

The -Xdoclint:none is an option of the standard doclet which will not work for custom doclets.

If you have a custom doclet and don't care about compilation errors, you can pass the --ignore-source-errors option either to the javadoc command line tool or to javax.tools.DocumentationTool.getTask(...) if you invoke your doclet programmatically.

The --ignore-source-errors option is not documented. Maybe because it might be removed in future. The clean way is to add all required libraries to the classpath (via the -classpath option to actually resolve the compilation errors).