Javadoc HTML erzeugen mit allen dependency

[werdas34]

Hallo,

ich möchte gerne ein Javadoc-Dokument erzeugen, indem alle dependency (pom.xml) mit berücksichtigt werden.
Bei Javadoc wird immer die Dokumentation für das eigene Projekt erstellt ohne dependency und JDK.
Mein Wunsch wäre es, wenn die pom die Junit5 als dependency hat, das die generierte Javadoc auch die Junit5 Docs mit anzeigt.

Idealerweise kann ich nur die JavaDoc vom pom erzeugen ohne das eigene Projekt, aber kein muss.

Wie stelle ich dass am besten an?

 

[KonradN]

Ich bin mir jetzt nicht sicher, ob ich Dich richtig verstanden habe. Du willst Details des Projekts in einer html Dokumentation haben?

Evtl. suchst Du dann das maven-site-plugin welches zu zusammen mit dem maven-project-info-reports-plugin verwenden kannst.

Apache Maven Site Plugin – Introduction
Apache Maven Project Info Reports Plugin – Introduction

Ich habe es jetzt nicht direkt ausprobiert, aber es könnte schon reichen, das site Plugin ohne Configuration einzubinden und bei dem Project Info Reports Plugin gibst Du eine verschachtelte Struktur an von reportSets > reportSet > reports > report
Bei den report Einträgen kannst Du mehrere haben. Du hast Dependencies erwähnt, also wird ein Eintrag <report>dependencies</report> aber es klang auch an, dass Du javadoc und test-javadoc haben willst.

Ach ja - der Eintrag von dem Project Info Reports Plugin kommt unter <reporting>! Das findet sich aber alles unter dem offiziellen Link z.B. siehst Du ein Beispiel unter
Apache Maven Site Plugin – Configuring Reports

mvn site sollte das dann eigentlich erzeugen und Du solltest es dann unter target/site finden.

Ist das in etwas, was Du brauchst? Oder habe ich Dich missverstanden?

 

[KonradN]

Ach - javadoc und test-javadoc kommen natürlich von maven-javadoc-plugin!
Das wäre das dritte Plugin im Bundle 🙂

 

[werdas34]

Ok. Ich muss mir das ganze erst mal anschauen.

ich habe eher mit so was gerechnet nur mit anderen Parametern:

javadoc -d doc src\*

Vielleicht ist es besser ich erkläre kurz den Hintergurnd.
Auf der Arbeit werden selbst entwickelte dependencies verwendet, deren öffentliche Doku sehr spärlich gehalten ist. Nur das nötigste quasi.

Meine Idee war es jetzt die Javadoc von diesen dependency zu erzeugen, so das ich ein "besseres" Nachschlagewerk habe, als die öffentliche Doku.
Die Javadoc müssen nicht jedesmal neu generiert werden, sondern dienen mir nur zuuurr Unterstützung.

Und was ist der Unterschied zwischen javadoc und test-javadoc? Hat das was damit zu tun, das ich als Beispiel Juni5 erwähnt habe. Also eigene Dokumentation für die Tests?

 

[KonradN]

Und ich habe das jetzt auch einmal in meinem JAdventure Projekt eingebunden. Wie das da aussehen könnte, siehst Du unter JAdventure/pom.xml at create-reports · kneitzel/JAdventure (github.com)
(Ist nicht im main Branch sondern in den Branches Lektion-3 und create-reports)

Und was ist der Unterschied zwischen javadoc und test-javadoc?

Einmal macht er src/main/java und das andere mach src/test/java

Meine Idee war es jetzt die Javadoc von diesen dependency zu erzeugen, so das ich ein "besseres" Nachschlagewerk habe, als die öffentliche Doku.

Haben die denn noch keine komplette JavaDoc? Wenn diese internen Libraries auch auf ein Maven Repository gepusht werden, dann sollte da auch das JavaDoc jar mit bereit gestellt werden.

Ich meine, dass man auch das JavaDoc von Dependencies mit einbinden kann, aber das habe ich noch nie gemacht. Beim JavaDoc Plugin kannst Du Dir mal diese Seite ansehen:
Apache Maven Javadoc Plugin – Aggregating Javadocs from Dependency Sources
Evtl. ist das ja, was Du suchst.

 

[werdas34]

Ah super. Ich werde es mir die kommenden Tage auch mal alles genauer ansehen.

Haben die denn noch keine komplette JavaDoc? Wenn diese internen Libraries auch auf ein Maven Repository gepusht werden, dann sollte da auch das JavaDoc jar mit bereit gestellt werden.

Also mir wurden schon sämtliche Orte gezeigt, wo relevante Dokumentationen zu finden sind, aber javadoc war nicht dabei. Ich werd da mal nachfragen.

Edit:;
Es gibt in InteillJ die Option Generate JavaDoc und dann die Checkbox Include JDK and library sources in -sourcepath.
Aber wenn ich das anwähle passiert nichts. Also es wird nur das HTML vom eigenen Projekt generiert, aber kein JDK oder dependencies.

 

[Oneixee5]

Javadoc sind Kommentare. Der Compiler entfernt im ersten Schritt alle Kommentare und Formatierungen. Also Javadoc aus einer Lib zu generieren ist nicht möglich. Man kann aber wie oben beschrieben, auf externe Dokumentationen zurückgreifen.

 

[LimDul]

Javadoc sind Kommentare. Der Compiler entfernt im ersten Schritt alle Kommentare und Formatierungen. Also Javadoc aus einer Lib zu generieren ist nicht möglich. Man kann aber wie oben beschrieben, auf externe Dokumentationen zurückgreifen.

Jein, von vielen Libs gibt es auch source-jars, da ist die Doku drin enthalten. Daraus könnte man dann die Doku bauen. Wenn keine source-jar dabei ist, hilft das natürlich nicht.

 

[KonradN]

selbst entwickelte dependencies verwendet,

Jein, von vielen Libs gibt es auch source-jars, da ist die Doku drin enthalten. Daraus könnte man dann die Doku bauen. Wenn keine source-jar dabei ist, hilft das natürlich nicht.

Also wenn die Abhängigkeiten selbst entwickelt wurden, dann sollte der Zugriff ja kein Problem sein.

 

[KonradN]

Ach ja - evtl. hilft es, wenn man die notwendigen Anpassungen nennt. Wenn diese Dependencies auch Maven Projekte sind, dann sollte man da ggf. etwas einfügen wie

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>${maven.javadoc.plugin}</version>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-source-plugin</artifactId>
                <version>${maven.source.plugin}</version>
                <executions>
                    <execution>
                        <id>attach-sources</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

        </plugins>
    </build>

Und natürlich die Versionen in den Properties setzen ...

 

[werdas34]

Ich habe jetzt zumindest auf meinen privaten Rechner eine für mich gute Lösung gefunden. Also ein paar dependency von der Arbeit getestet.
Sorry @KonradN hat nichts mit dem zutun was du gepostet hast. Ich habs mir angeschaut, aber hat nicht funktioniert. Muss mich definitiv mehr mit Maven beschäftigen..

Man kann in IntelliJ in den Setting unter Maven -> Importing Automatically download [] Sources [] Documentation [] Annotation.
Wenn man alle aktiviert werden alle Docus bzw sources-jar gedownloaded und man kann die javadoc in der IDE direkt sehen. Und man kommt über einen kleinen Umweg direkt HTML. Passt also.

Nun habe ich versucht die Settings bei meinem Arbeitslaptop einzustellen, aber am Ende wird mir dennoch keine Docu angezeigt. Und ich habe privat und auf dem Arbeitsrechner die SpringApplication Klasse getestet. Privat Rechner funktioniert.
Auf der Arbeit haben mir Nexus und einen VPN. Habe mich auch im VPN angemeldet und die pom neu geladen. Funktioniert nicht.

Jemand ne Idee?

 

[KonradN]

Maven hat eine update Policy, die vorgibt, wie oft es nach neuen Versionen schaut. Das trifft leider auch auf den Fall zu, dass es versucht hat, etwas herunter zu laden und es fehlgeschlagen ist. Das heisst: Weil der Download nicht geklappt hat, wird es eine Zeit lang (default 1 Tag) nicht erneut probiert. Man kann mit der Option -U aber den erneuten Check erzwingen. Also z.B. ein mvn -U package ausführen.

In IntelliJ kannst Du dies z.B. über das Maven Toolfenster machen. Dazu dort den Knopf "Execute Maven Goal" auswählen und dann hast Du im PopUp oben eine Eingabezeile, in der schon mvn steht. Da einfach das -U package eingeben.

Sorry @KonradN hat nichts mit dem zutun was du gepostet hast.

Das muss Dir nicht leid tun. Es tut mir leid, dass ich Dein Problem nicht besser verstanden habe. Dein Problem war somit nicht, dass Du da etwas erzeugen wolltest sondern dass es Dir in IntelliJ gefehlt hat.

Deine Lösung mit diesen Einstellungen war somit goldrichtig und danke für das Teilen der Lösung.

Falls man gerne mit der Kommandozeile arbeitet: Das kann man auch auf der Kommandozeile erreichen über ein
mvn dependency:sources dependency:resolve -Dclassifier=javadoc

Das dependency:sources lädt von den Abhängigkeiten die Source Jars herunter und
das dependency:resolve -Dclassifier=javadoc lädt die JavaDocs herunter.

Somit könntest Du auch ausführen:
mvn -U dependency:sources dependency:resolve -Dclassifier=javadoc


Ach ja - prinzipiell könnte man in der Maven Konfiguration auch die updatePolicy umsetzen auf always:
Maven – Settings Reference (apache.org)
Ob das aber Sinn macht muss jeder für sich entscheiden. Ich habe es bei mir unverändert gelassen und wenn ich ein Problem (ähnlich wie bei Dir) feststelle, dann nutze ich -U.