Игнорировать незначительные ошибки, используя javadoc

Я пытаюсь создать документацию, используя javadoc, из одного или двух загруженных файлов jar (с исходным кодом, конечно, после того, как вы извлекли все).

Но с помощью javadoc, даже в файле Ant, мне не удалось создать это из-за глупых вещей, в частности, "пакет XXX не существует" и "не может найти символ"... Я просто хочу, чтобы javadoc поместите текст этих вещей (внешние ссылки) в документы html, но запишите все найденные файлы .java...

NB для всех, кому это интересно, это страница загрузки с файлами загрузки (содержащей источник), из которых я пытаюсь создать документацию по API: http://logback.qos.ch/download.html

Следуя команде Mark Rotteveel, мой файл сборки Ant теперь выглядит следующим образом:

<?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>

... но он все еще дает ошибки 1) о не найденных пакетах, включая "org.codehaus. [xxx...]" и "javax.mail. [xxx...]" и 2) о символах не обнаруживается (хотя это может исчезнуть, если я могу решить недостающие ошибки пакетов).

NB, сборка считается успешной, но я получаю жалобы о том, что исходные файлы не найдены (там, где действительно есть комментарии .java файлов), а html вообще не создается в \javadoc.

позже, после успеха Тони Пирса в создании этих документов

Установлен Ant 1.9.6, изменен путь соответственно, проверен, чтобы убедиться, что это была используемая версия... попробовал еще раз. Сбой снова. Это был конец моего вывода:

[Javadoc] D:\Desktop\Загрузки\Logback-1.1.7.tar\Logback-1.1.7\Logback-ядро\SRC\Test\Java\ч\QoS\Logback\ядро \ Appender\ConsoleAppenderTest.java: 32: Ошибка: пакет org.junit не существует
[javadoc] import static org.junit.Assert.assertEquals;
[Javadoc] _______________________ ^

[javadoc] javadoc: ошибка - не было обнаружено никаких открытых или защищенных классов документ.
[javadoc] 1 ошибка
[javadoc] 100 предупреждений

BUILD SUCCESSFUL Общее время: 2 секунды

Он создает папку javadoc... но это пусто.

NB о вышеупомянутой ошибке "пакет не существует" (было много других): это особенно мистифицирует, поскольку я думал, что Ant как-то включал junit по умолчанию (NB Я полный новичок в Ant, просто работая через "Ant в действии" ).

Но... с помощью задачи Ant javac вы можете установить includeAntRuntime="true"... согласно этой книге, которая включает Ant собственный junit.jar. К сожалению, задача javadoc не поддерживает этот атрибут.

позже

Мое мышление было немного запутано в этом, если честно: самый простой способ, который я нашел для компиляции javadocs из сторонних источников, - это просто извлечь, а затем использовать командную строку, как правило:

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

... как для javadoc для одного собственного кода это не кажется проблемой в Gradle (я только мельком смотрел на Ant, осознавая, что будущее Gradle... и это не особенно сложно понять с помощью основ).

NB Если вы устанавливаете плагин Gradle STS для Eclipse, а затем создаете новый проект с помощью мастера Gradle STS, ваш файл сборки содержит строку

применить плагин: 'eclipse'

... одним из эффектов которого является то, что по умолчанию исходный код, а также исполняемые файлы для всех ваших сторонних зависимостей будут загружены в GRADLE_HOME во время сборки. Довольно хорошо!

Ответ 1

В Java 8 представлен doclint, который будет обрабатывать определенные проблемы как ошибку и не создавать документацию. Это можно отключить, указав опцию командной строки -Xdoclint:none.

Смотрите также: Отключение doclint в JDK 8 Javadoc

Например, в Ant вам нужно добавить атрибут additionalparam="-Xdoclint:none" в задачу javadoc. A (слегка измененный) пример от 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>

Ответ 2

Я немного упростил ваш файл сборки и успешно создал javadoc. Вот что я сделал:

Загрузили журнал zip
Развернул исходные банки внутри каталога src

Ran ant 1.9.6 под java 8 с этим:

<?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>

Он подготовил много предупреждений, но создал каталог javadoc, заполненный html.

Я удалил excludepackagenames и сбросил элемент packagenames. В любом случае packagenames="main.*" предотвращает генерацию javadoc, потому что единственные корневые пакеты в банке: ch и org.