Javadoc of interfaces are not included in generation

[FroMage]

Reported by [email protected], Yesterday (22 hours ago) What steps will reproduce the problem?

1. 2 maven modules, one with a jax-rs annotated inteface (module A) and one module with the implementation (module B).
2. Let a java class in module B implement the jax-rs annotated interface in module A.
3. generate the documentation for module B using maven. Note that the implementation class has no further java doc. Everything is on the interface.

What is the expected output? What do you see instead? Expected is a documentation with all comments from the implemented interface but you get a documentation where all the rest resources are listed but without any java doc written on the interface. It seems that the java doc from the interface is completely ignored but the annotations from the interface are considered.

What version of the product are you using? On what operating system? 0.9.0 on WinXP/Linux.

Please provide any additional information below.

[FroMage]

I think it's a source issue, javadoc needs to have access to the source of the first module for this to work.

[calebjones]

I'm getting successful generation of docs from interfaces.

Note: my interfaces sources are accessible to maven at build time.

[stanio]

I'm using the same configuration - interface module A (containing the JAX-RS annotated interfaces and types) and implementation module B (depending on A), and I'm having the same problem. I would appreciate specific configuration example solving the issue. I'm getting empty documentation generated when configured on the interface module A, also.

[stanio]

Issue #2 "Generate documentation based on interface (without any implementation)" seems related.

[calebjones]

There's not much to my config. I have multiple interfaces that are annotated with annotations from javax.ws.rs. Absolutely no JAX-RS annotations exist down in my implementations.

Other than that, my code is a standard maven2 project.

Here's my pom.xml reporting snippet:

<reporting>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>cobertura-maven-plugin</artifactId>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.7</version>
            <reportSets>
                <reportSet>
                    <configuration>
                        <name>REST Doclets</name>
                        <description>JAXRS-based auto-generated RESTful Doclets</description>
                        <header>
                            <![CDATA[My custom HTML header]]>
                        </header>
                        <footer>
                            <![CDATA[My custom HTML footer]]>
                        </footer>
                        <stylesheetfile>${basedir}/src/site/css/custom.css</stylesheetfile>
                        <doclet>com.lunatech.doclets.jax.jaxrs.JAXRSDoclet</doclet>
                        <docletArtifacts>
                            <docletArtifact>
                                <groupId>com.lunatech.jax-doclets</groupId>
                                <artifactId>doclets</artifactId>
                                <version>0.9.0</version>
                            </docletArtifact>
                        </docletArtifacts>
                        <destDir>jaxrsdocs</destDir>
                    </configuration>
                    <reports>
                        <report>javadoc</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>

[stanio]

The above configuration may work if you have both the interfaces and implementation classes in the same module (I didn't actually got what's your configuration regarding "my interfaces sources are accessible to maven at build time").

So, the doclet doesn't basically work when configured on the interface module A, because of issue #2. It works when configured on the implementation module B which declares dependency on module A and the javadoc plugin configuration have to include:

    <configuration>
        ...
        <includeDependencySources>true</includeDependencySources>
        ...
    </configuration>

Module A have to be configured to install sources artifact, also:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <version>2.1.2</version>
        <executions>
            <execution>
                <id>attach-sources</id>
                <phase>verify</phase>
                <goals>
                    <goal>jar-no-fork</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

[FroMage]

Guys, sorry I won't have time to look into this issue before a while, but if you manage to find and fix the issue I'll merge your pull request.