Skip to content

Javadoc

Jump to bottom
Vojtěch Habarta edited this page Mar 3, 2016 · 1 revision

typescript-generator can include Javadoc comments in the output. For example from this class with Javadoc comments:

/**
 * This represents real person.
 */
public class Person {
    /**
     * Person full name.
     */
    public String name;
}

typescript-generator can generate this TypeScript declaration with JSDoc comments:

/**
  * This represents real person.
  */
interface Person {
    /**
      * Person full name.
      */
    name: string;
}

Javadoc file

Since Javadoc comments are not available in runtime we have to use Javadoc tool first and extract comments to file. Typescript generator uses XML format defined by xml-doclet. When we have one or more files with comments typescript-generator is able to use these files and add comments to generated output.

Maven

If you are using maven here is example how to configure maven-javadoc-plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
    <executions>
        <execution>
            <id>xml-doclet</id>
            <phase>process-classes</phase>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <configuration>
                <doclet>com.github.markusbernhardt.xmldoclet.XmlDoclet</doclet>
                <additionalparam>-d ${project.build.directory}</additionalparam>
                <useStandardDocletOptions>false</useStandardDocletOptions>
                <docletArtifact>
                    <groupId>com.github.markusbernhardt</groupId>
                    <artifactId>xml-doclet</artifactId>
                    <version>1.0.5</version>
                </docletArtifact>
            </configuration>
        </execution>
    </executions>
</plugin>

Javadoc XML file is saved to target/javadoc.xml and typescript-generator can use it as follows:

<plugin>
    <groupId>cz.habarta.typescript-generator</groupId>
    <artifactId>typescript-generator-maven-plugin</artifactId>
    <version>1.6.x</version>
    <executions>
        <execution>
            <id>generate</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <phase>process-classes</phase>
            <configuration>
                <jsonLibrary>jackson2</jsonLibrary>
                <classes>
                    <class>cz.habarta.typescript.generator.Person</class>
                </classes>
                <javadocXmlFiles>
                    <file>target/javadoc.xml</file>
                </javadocXmlFiles>
                <outputFile>target/rest.d.ts</outputFile>
            </configuration>
        </execution>
    </executions>
</plugin>

Multi-module setup

Previous example assumes you run typescript-generator in the same maven module where source code for JSON classes is located. If you have sources in different module you can run Javadoc tool in this module, attach packed Javadoc XML file to module output and then use it in dependent module.

So suppose we have module client where typescript-generator is run. This module has two dependencies s1 and s2 with JSON classes. First we use maven-javadoc-plugin in modules s1 and s2 to generate and attach Javadoc XML files:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.10.3</version>
    <executions>
        <execution>
            <id>xml-doclet</id>
            <phase>process-classes</phase>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <doclet>com.github.markusbernhardt.xmldoclet.XmlDoclet</doclet>
                <destDir>${project.build.directory}/xml-javadoc</destDir>
                <classifier>xml-javadoc</classifier>
                <useStandardDocletOptions>false</useStandardDocletOptions>
                <docletArtifact>
                    <groupId>com.github.markusbernhardt</groupId>
                    <artifactId>xml-doclet</artifactId>
                    <version>1.0.5</version>
                </docletArtifact>
            </configuration>
        </execution>
    </executions>
</plugin>

Then we use maven-dependency-plugin in client module to copy and unpack Javadoc files from s1 and s2 modules:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>2.10</version>
    <executions>
        <execution>
            <id>unpack-javadoc</id>
            <phase>process-classes</phase>
            <goals>
                <goal>unpack</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>example</groupId>
                        <artifactId>s1</artifactId>
                        <classifier>xml-javadoc</classifier>
                        <outputDirectory>${project.build.directory}/xml-javadoc/s1</outputDirectory>
                    </artifactItem>
                    <artifactItem>
                        <groupId>example</groupId>
                        <artifactId>s2</artifactId>
                        <classifier>xml-javadoc</classifier>
                        <outputDirectory>${project.build.directory}/xml-javadoc/s2</outputDirectory>
                    </artifactItem>
                </artifactItems>
                <includes>javadoc.xml</includes>
            </configuration>
        </execution>
    </executions>
</plugin>

and configure typescript-generator-maven-plugin to use these files:

<plugin>
    <groupId>cz.habarta.typescript-generator</groupId>
    <artifactId>typescript-generator-maven-plugin</artifactId>
    <version>1.6.x</version>
    <executions>
        <execution>
            <id>generate</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <phase>process-classes</phase>
            <configuration>
                <jsonLibrary>jackson2</jsonLibrary>
                <classes>
                    <class>cz.habarta.typescript.generator.Person</class>
                </classes>
                <javadocXmlFiles>
                    <file>${project.build.directory}/xml-javadoc/s1/javadoc.xml</file>
                    <file>${project.build.directory}/xml-javadoc/s2/javadoc.xml</file>
                </javadocXmlFiles>
                <outputFile>target/rest.d.ts</outputFile>
            </configuration>
        </execution>
    </executions>
</plugin>
Clone this wiki locally