Ignoruj ​​drobne błędy za pomocą javadoc

Question

Próbuję wygenerować dokumentację, używając javadoc, z jednego lub dwóch pobranych plików jar (ze źródłem oczywiście, po wyodrębnieniu wszystkiego).

Ale używanie javadoc, nawet w pliku Ant, uniemożliwia mi generowanie tego z powodu głupich rzeczy, w szczególności "pakiet XXX nie istnieje" i "nie można znaleźć symbolu" ... Po prostu chcę umieścić javadoc tekst tych rzeczy (odnośniki zewnętrzne) w dokumentach HTML, ale aby udokumentować wszystkie znalezione pliki .java ...

Uwaga dla wszystkich zainteresowanych jest to strona pobierania z plikami do pobrania (zawierającymi źródło), z których Próbuję wygenerować dokumentację API: http://logback.qos.ch/download.html

Po pomoc Mark Rotteveel za mój plik build Ant teraz wygląda tak:

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

... ale nadal daje błędy 1) o nieodnalezieniu pakietów, w tym "org.codehaus. [Xxx ...]" i "javax.mail. [Xxx ...]" i 2) o nieodnalezieniu symboli (chociaż może to zniknąć, jeśli mogę rozwiązać błędy brakujących pakietów).

Pamiętaj, że kompilacja została uznana za udaną, ale dostaję skargi na to, że nie znaleziono plików źródłowych (gdzie rzeczywiście są skomentowane pliki .java), a żaden HTML nie jest generowany w \ javadoc.

później, po sukcesie Tony Pierce w generowaniu te dokumenty

Zainstalowane Ant 1.9.6, zmienił ścieżkę odpowiednio, sprawdzane, aby upewnić się, że była to wersja używana ... spróbował ponownie. Ponowne niepowodzenie. To był koniec mojej produkcji:

[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

Tworzy folder javadoc ... ale jest pusty.

Uwaga na powyższy błąd "pakiet nie istnieje" (było wiele innych): ten jest szczególnie tajemniczy, ponieważ domyślam się, że Ant jakoś włączyła domyślnie junit (NB: Jestem kompletnym nowicjuszem w Ant, po prostu pracuję przez " Ant in Action ").

Ale ... z zadaniem Ant javac można ustawić includeAntRuntime="true" ... zgodnie z tą książką, która dodaje, że Ant ma własny junit.jar. Niestety zadanie javadoc nie obsługuje tego atrybutu.

później jeszcze

Moje myślenie było trochę zagmatwane na to, aby być uczciwym: najprostszym sposobem znalazłem kompilacji Javadocs ze słoików źródłowych zewnętrznych jest tylko przez ekstrakcję, a następnie za pomocą wiersz polecenia, zwykle:

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

... jak dla javadoc dla własnego kodu to nie wydaje się być problemem w Gradle (ja glimpsing tylko w Ant, świadomość, że przyszłość jest Gradle ... i nie jest to szczególnie trudne chwyty z podstawami).

NB Jeśli zainstalować wtyczkę Gradle STS dla Eclipse, a następnie utworzyć nowy projekt przy użyciu kreatora Gradle STS plik build zawiera linię

apply plugin: 'eclipse'

... jednym z efektów których jest to, że domyślnie źródło, jak również pliki wykonywalne dla wszystkich twoich zewnętrznych zależności będą pobierane pod GRADLE_HOME podczas kompilacji. Całkiem dobre!

Answer 1

Java 8 wprowadziła doclint, które będą traktować niektóre problemy jako błąd i nie będą tworzyć dokumentacji. Można to wyłączyć, określając opcję linii poleceń: -Xdoclint:none.

Zobacz także: Turning off doclint in JDK 8 Javadoc

Np w Ant trzeba by zrobić dodać atrybut additionalparam="-Xdoclint:none" do zadania javadoc. A (nieznacznie zmodyfikowany) przykład z 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

Uproszyłem nieco plik budowy i pomyślnie zbudowałem javadoc. Oto co zrobiłem:

• Pobrano zip logback
• Expanded źródeł wewnątrz bańki w src katalogu

• Ran ant 1.9.6 pod java 8 z tym:

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

Wyprodukowano wiele ostrzeżeń, ale utworzono katalog javadoc wypełniony html.

Usunąłem excludepackagenames i usunąłem element packagenames. W każdym razie, packagenames="main.*" zapobiega generacji javadoc, ponieważ jedynymi pakietami root w słoiku są ch i org.