Home > Back-end >  Java 8: How to use javadoc aggregate
Java 8: How to use javadoc aggregate

Time:12-04

Introduction

I'm currently contributing to a GitHub project.
For this, I'm writing a GitHub workflow inside a GitHub Action that tests the creation of JavaDoc files.
This workflow should be run with act.
The project of the GitHub Action when I want to add this GitHub Workflow: https://github.com/MathieuSoysal/Javadoc-publisher.yml

Problem

The problem, when I execute my GitHub workflow with act I obtain this error.

| [INFO] Configuration changed, re-generating javadoc.
| [INFO] 
| Usage: javadoc [options] [packagenames] [sourcefiles] [@files]
|   -overview <file>                 Read overview documentation from HTML file
|   -public                          Show only public classes and members
|   -protected                       Show protected/public classes and members (default)
|   -package                         Show package/protected/public classes and members
|   -private                         Show all classes and members
|   -help                            Display command line options and exit
|   -doclet <class>                  Generate output via alternate doclet
|   -docletpath <path>               Specify where to find doclet class files
|   -sourcepath <pathlist>           Specify where to find source files
|   -classpath <pathlist>            Specify where to find user class files
|   -cp <pathlist>                   Specify where to find user class files
|   -exclude <pkglist>               Specify a list of packages to exclude
|   -subpackages <subpkglist>        Specify subpackages to recursively load
|   -breakiterator                   Compute first sentence with BreakIterator
|   -bootclasspath <pathlist>        Override location of class files loaded
|                                    by the bootstrap class loader
|   -source <release>                Provide source compatibility with specified release
|   -extdirs <dirlist>               Override location of installed extensions
|   -verbose                         Output messages about what Javadoc is doing
|   -locale <name>                   Locale to be used, e.g. en_US or en_US_WIN
|   -encoding <name>                 Source file encoding name
|   -quiet                           Do not display status messages
|   -J<flag>                         Pass <flag> directly to the runtime system
|   -X                               Print a synopsis of nonstandard options and exit
| 
| Provided by Standard doclet:
|   -d <directory>                   Destination directory for output files
|   -use                             Create class and package usage pages
|   -version                         Include @version paragraphs
|   -author                          Include @author paragraphs
|   -docfilessubdirs                 Recursively copy doc-file subdirectories
|   -splitindex                      Split index into one file per letter
|   -windowtitle <text>              Browser window title for the documentation
|   -doctitle <html-code>            Include title for the overview page
|   -header <html-code>              Include header text for each page
|   -footer <html-code>              Include footer text for each page
|   -top    <html-code>              Include top text for each page
|   -bottom <html-code>              Include bottom text for each page
|   -link <url>                      Create links to javadoc output at <url>
|   -linkoffline <url> <url2>        Link to docs at <url> using package list at <url2>
|   -excludedocfilessubdir <name1>:.. Exclude any doc-files subdirectories with given name.
|   -group <name> <p1>:<p2>..        Group specified packages together in overview page
|   -nocomment                       Suppress description and tags, generate only declarations.
|   -nodeprecated                    Do not include @deprecated information
|   -noqualifier <name1>:<name2>:... Exclude the list of qualifiers from the output.
|   -nosince                         Do not include @since information
|   -notimestamp                     Do not include hidden time stamp
|   -nodeprecatedlist                Do not generate deprecated list
|   -notree                          Do not generate class hierarchy
|   -noindex                         Do not generate index
|   -nohelp                          Do not generate help link
|   -nonavbar                        Do not generate navigation bar
|   -serialwarn                      Generate warning about @serial tag
|   -tag <name>:<locations>:<header> Specify single argument custom tags
|   -taglet                          The fully qualified name of Taglet to register
|   -tagletpath                      The path to Taglets
|   -charset <charset>               Charset for cross-platform viewing of generated documentation.
|   -helpfile <file>                 Include file that help link links to
|   -linksource                      Generate source in HTML
|   -sourcetab <tab length>          Specify the number of spaces each tab takes up in the source
|   -keywords                        Include HTML meta tags with package, class and member info
|   -stylesheetfile <path>           File to change style of the generated documentation
|   -docencoding <name>              Specify the character encoding for the output
| 1 error
| [INFO] ------------------------------------------------------------------------
| [INFO] BUILD FAILURE
| [INFO] ------------------------------------------------------------------------
| [INFO] Total time:  15.675 s
| [INFO] Finished at: 2022-12-04T09:34:07Z
| [INFO] ------------------------------------------------------------------------
| [ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.4.0:aggregate (default-cli) on project template: An error has occurred in Javadoc report generation: 
| [ERROR] Exit code: 1 - javadoc: error - invalid flag: --release
| [ERROR] 
| [ERROR] Command line was: /opt/hostedtoolcache/Java_Adopt_jdk/8.0.345-1/x64/jre/../bin/javadoc @options @packages
| [ERROR] 
| [ERROR] Refer to the generated Javadoc files in '/workspaces/Javadoc-publisher.yml/target/site/apidocs' dir.
| [ERROR] 
| [ERROR] -> [Help 1]
| [ERROR] 
| [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
| [ERROR] Re-run Maven using the -X switch to enable full debug logging.
| [ERROR] 
| [ERROR] For more information about the errors and possible solutions, please read the following articles:
| [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

GitHub Workflow

My GitHub Workflow :

name: Test Actions

on: [pull_request, push]

jobs:
  test:
    runs-on: ubuntu-latest
    
    name: Test with Java 8
    steps:
      - uses: actions/checkout@v3
      - uses: ./ # Uses an action in the root directory
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          javadoc-branch: javadoc-test
          java-version: 8
          target-folder: javadoc

      - uses: GuillaumeFalourd/assert-command-line-output@v2
        with:
          command_line: ls -lha
          contains: javadoc
          expected_result: PASSED

GitHub Action

The GitHub Action of the project : https://github.com/MathieuSoysal/Javadoc-publisher.yml/blob/main/action.yml

mvn command

The executed command to generate javadoc: mvn org.apache.maven.plugins:maven-javadoc-plugin:3.4.0:aggregate

Java version

The java version is: Java Adopt 8.0.345-1

pom.xml

The pom.xml of the project:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- FIXME replace pseudo-->
    <groupId>io.github.pseudo</groupId>
    <!-- FIXME replace name -->
    <artifactId>template</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>


    <!-- FIXME replace template-->
    <name>template</name>
    <!-- FIXME replace www.example.com-->
    <url>http://www.example.com</url>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <java.version>8</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <maven.compiler.release>${java.version}</maven.compiler.release>
        <junit>5.9.0</junit>

        <!-- Plugin versions -->
        <maven.shade>3.3.0</maven.shade>
        <maven.clean>3.1.0</maven.clean>
        <maven.resources>3.1.0</maven.resources>
        <maven.compiler>3.8.1</maven.compiler>
        <maven.surefire>3.0.0-M5</maven.surefire>
        <maven.jar>3.2.0</maven.jar>
        <maven.install>3.0.0-M1</maven.install>

        <!-- SonarCloud properties -->
        <!-- FIXME replace with your SonarCloud organization on https://sonarcloud.io -->
        <sonar.organization>mathieusoysal</sonar.organization>
        <sonar.host.url>https://sonarcloud.io</sonar.host.url>
    </properties>

    <dependencies>
        <!-- Dependencies -->


        <!-- Testing dependencies-->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>${junit}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>${junit}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-params</artifactId>
            <version>${junit}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <artifactId>maven-clean-plugin</artifactId>
                <version>3.2.0</version>
            </plugin>
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.3.0</version>
            </plugin>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.10.1</version>
            </plugin>
            <plugin>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.0.0-M7</version>
            </plugin>
            <plugin>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.2</version>
            </plugin>
            <plugin>
                <artifactId>maven-install-plugin</artifactId>
                <version>3.0.1</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>${maven.shade}</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <transformers>
                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                    <!-- FIXME replace io.github.pseudo.App-->
                                    <mainClass>io.github.pseudo.App</mainClass>
                                </transformer>
                            </transformers>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <artifactId>maven-site-plugin</artifactId>
                <version>3.12.0</version>
            </plugin>
            <plugin>
                <artifactId>maven-project-info-reports-plugin</artifactId>
                <version>3.4.0</version>
            </plugin>
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.8.8</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>report</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>report</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Question

Does someone know how we can fix this javadoc aggregate problem with jdk 8?

CodePudding user response:

Please remove:

<maven.compiler.release>${java.version}</maven.compiler.release>

with

  • your pom,
  • a trivial code base,
  • mvn clean javadoc:aggregate

, I can't even compile:

...

--- maven-compiler-plugin:3.10.1:compile (default-compile) @ template ---
Changes detected - recompiling the module!
Compiling 1 source file to C:\DEV\projects\java8-demo\target\classes
------------------------------------------------------------------------
BUILD FAILURE
------------------------------------------------------------------------
Total time:  1.025 s
Finished at: 2022-12-04T13:09:35 01:00...
------------------------------------------------------------------------
Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.10.1:compile (default-compile) on project template: Fatal error compiling: invalid flag: --release -> [Help 1]

(invalid flag: --release)

Whereas

  • Commenting/deleting <maven.compiler.release/>

... gives us:

cd C:\DEV\projects\java8-demo; 
"JAVA_HOME=C:\\Program Files\\Java\\jdk1.8.0_333" M2_HOME=C:\\ProgramData\\chocolatey\\lib\\maven\\apache-maven-3.8.6
mvn clean javadoc:aggregate
Scanning for projects...

---------------------< io.github.pseudo:template >----------------------
Building template 1.0-SNAPSHOT
--------------------------------[ jar ]---------------------------------

--- maven-clean-plugin:3.2.0:clean (default-clean) @ template ---
Deleting C:\DEV\projects\java8-demo\target

---------------------< io.github.pseudo:template >----------------------
Building template 1.0-SNAPSHOT
--------------------------------[ jar ]---------------------------------

>>> maven-javadoc-plugin:3.4.1:aggregate (default-cli) > compile @ template >>>

--- jacoco-maven-plugin:0.8.8:prepare-agent (default) @ template ---
argLine set to -javaagent:C:\\Users\\xerx\\.m2\\repository\\org\\jacoco\\org.jacoco.agent\\0.8.8\\org.jacoco.agent-0.8.8-runtime.jar=destfile=C:\\DEV\\projects\\java8-demo\\target\\jacoco.exec

--- maven-resources-plugin:3.3.0:resources (default-resources) @ template ---
skip non existing resourceDirectory C:\DEV\projects\java8-demo\src\main\resources

--- maven-compiler-plugin:3.10.1:compile (default-compile) @ template ---
Changes detected - recompiling the module!
Compiling 1 source file to C:\DEV\projects\java8-demo\target\classes

<<< maven-javadoc-plugin:3.4.1:aggregate (default-cli) < compile @ template <<<


--- maven-javadoc-plugin:3.4.1:aggregate (default-cli) @ template ---
No previous run data found, generating javadoc.

Loading source file C:\DEV\projects\java8-demo\src\main\java\com\example\java8\demo\App.java...
Loading source files for package com.example.java8.demo...
Constructing Javadoc information...
Standard Doclet version 1.8.0_333
Building tree for all the packages and classes...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\com\example\java8\demo\App.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\com\example\java8\demo\package-frame.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\com\example\java8\demo\package-summary.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\com\example\java8\demo\package-tree.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\constant-values.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\com\example\java8\demo\class-use\App.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\com\example\java8\demo\class-use\App.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\com\example\java8\demo\package-use.html...
Building index for all the packages and classes...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\overview-tree.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\index-all.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\deprecated-list.html...
Building index for all classes...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\allclasses-frame.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\allclasses-noframe.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\index.html...
Generating C:\DEV\projects\java8-demo\target\site\apidocs\help-doc.html...
------------------------------------------------------------------------
BUILD SUCCESS
------------------------------------------------------------------------
Total time:  3.287 s
Finished at: 2022-12-04T13:20:08 01:00
------------------------------------------------------------------------

..the (slight) difference in maven-javadoc-plugin version should be explained by different maven versions. (we can fix it in <build.[pluginManagement.]plugins/>)

  • Related