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!

Mark Rotteveel · Answer 1 · 2016-07-28T07:25:41.053

9

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>

edited Jul 28 '16 at 07:25

answered Jul 28 '16 at 07:19

Mark Rotteveel

100,966
191
140
197

Thanks... in fact I had come across this. I tried it when running javadoc from the command line (not using Ant). But in fact I couldn't get anywhere with using the command line either. Ah... just seen your edit... thanks again... going to study it... – mike rodent Jul 28 '16 at 07:25
tried running with this additionalparam... same results. Can you possibly show the bit of your build file where you define excludedPackages? – mike rodent Jul 28 '16 at 07:30
@mikerodent https://github.com/FirebirdSQL/jaybird/blob/master/build/init.xml#L198 Note that if the problem is external references, you might need to look at either the `classpath` elements (so you have dependencies on the classpath), or the `link` element (which in my case points to the JDK api docs). – Mark Rotteveel Jul 28 '16 at 07:34
can I "bump" you on this? If you could show how to generate the javadoc from the logback.qos.ch/download.html downloads (with source), without the org.codehaus or javax.mail jars, I'd be happy to award the 50 point bounty! – mike rodent Aug 02 '16 at 20:55
@mikerodent Unfortunately I don't have time to do that. – Mark Rotteveel Aug 05 '16 at 06:58

score 8 · Answer 2 · answered Sep 01 '20 at 08:12

8

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).

answered Sep 01 '20 at 08:12

Marteng

1,179
13
31

Thanks for the `--ignore-source-errors` option. :) – Christopher Sep 06 '21 at 11:36
This worked with a Javadoc gradle task that was failing on Java 11 (and previously working with Java 8). My problem was caused as I need to exclude the "internal" package from the documentation. Why this option is undocumented is a mystery for me. – franmontiel Nov 24 '21 at 16:14
@Marteng How would you declare this option in a Gradle task, exactly? – Ivan Garza Dec 10 '22 at 00:00

score 0 · Answer 3 · edited Aug 06 '16 at 06:57

I simplified your build file a bit and built the javadoc successfully. Here's what I did:

Downloaded the logback zip
Expanded the sources jars inside into a src directory

Ran ant 1.9.6 under java 8 with this:

<?xml version="1.0" ?>
<project name="document logback core" default="doc">
    <target name="doc">
        <mkdir dir="javadoc" />
        <javadoc destdir="javadoc" sourcepath="src" 
            additionalparam="-Xdoclint:none" />
    </target>
</project>

It produced a lot of warnings, but created a javadoc directory filled with html.

I removed excludepackagenames and dropped the packagenames element. In any case, packagenames="main.*" prevents the javadoc generation because the only root packages in the jar are ch and org.

Thanks. Tried it... no HTML or anything generated. Only difference I can see is that I'm using Ant 1.9.7! Over the weekend I'll try to find time to use Ant 1.9.6... Could it be a mystifying Windoze permission thing? — mike rodent, Aug 05 '16 at 10:23

score 0 · Answer 4 · answered Jun 16 '23 at 15:37

Just in addition to the answers above, when using ANT: 1.10.13 with Java: 17.0.6, my build would not complete due to javadoc errors. Adding additionalparam attribute to the javadoc task did not work, but using arg elements for each argument did:

<javadoc>
    <arg value="--ignore-source-errors"/>
    <arg value="-Xdoclint:none"/>
</javadoc>

With this javadoc HTML was still generated, and my build was successful.

Ignore minor errors using javadoc

4 Answers4

Linked