Docerina - Ballerina API Documentation

Docerina is the API documentation generator tool of the Ballerina language. Currently API documentation is generated in HTML format and it can be extended to support additional formats as required. You can think of this as a Javadoc equivalent of the Ballerina language.

We have hosted the Ballerina Native API documentation which is generated automatically via Docerina at http://ballerinalang.org/docs/api/0.8/.

Sample API Documentation generated via Docerina

Supported Annotations

Annotations

The following annotations are available in Ballerina for documenting APIs:

• @doc:Description: Use description annotation for explaining the purpose of functions, connectors, connector actions and structs.
• @doc:Param: Use param annotation for explaining parameters.
• @doc:Return: Use return annotation for explaining return parameters.
• @doc:Field: Use field annotation for explaining fields of structs.

Annotating Functions

Following is a sample function with documentation annotations:

@doc:Description("Add HTTP header to the message")
@doc:Param("m: Incoming message")
@doc:Param("key: HTTP header key")
@doc:Param("value: HTTP header value")
@doc:Return("result: Result of the execution")
function addHeader (message m, string key, string value) (boolean result) {
    system:println("invoked");
    return true;
}

Annotating Connectors

Following is a sample connector with documentation annotations:

package foo.bar;
@doc:Description("Heapster Connector")
@doc:Param("accessToken: Access Token")
@doc:Param("endpointUrl: Heapster endpoint URL")
@doc:Param("retryCount: Retry count")
connector HeapsterConnector(string accessToken, string endpointUrl, int retryCount) {
    @doc:Description("Get CPU usage of a conatiner")
    @doc:Param("c: connector object")
    @doc:Param("containerId: Id of the container")
    @doc:Return("cpu: CPU usage")
    action getCpuUsage(HeapsterConnector c, string containerId) (int cpuUsage) {
        // Find CPU usage of container
        return cpuUsage;
    }
    @doc:Description("Get Memory usage of a conatiner")
    @doc:Param("c: connector object")
    @doc:Param("containerId: Id of the container")
    @doc:Return("memoryUsage: Memory usage")
    action getCpuUsage(HeapsterConnector c, string containerId) (int memoryUsage) {
        // Find memory usage of container
        return memoryUsage;
    }
}

Annotating Structs

Following is a sample struct with documentation annotations:

package foo.bar;
@doc:Description("Inventory part definition")
@doc:Field("partId: Part ID")
@doc:Field("description: Part description")
@doc:Field("brand: Brand of the part")
struct InventoryPart {
    int partId;
    string description;
    string brand;
}

Generating Ballerina API Documentation

Docerina is distributed with Ballerina Tools Distribution and Docerina Maven Plugin.

Using Ballerina Tools Distribution

Ballerina doc command can be used to generate the API documentation for your Ballerina programs.

$ ballerina doc --help
generate Ballerina API documentation
Usage:
ballerina doc <sourcepath>... [-o outputdir] [-n] [-e excludedpackages] [-v]
  sourcepath:
  Paths to the directories where Ballerina source files reside or a path to
  a Ballerina file which does not belong to a package
Flags:
  --output, -o     path to the output directory where the API documentation will be written to
  --native, -n     read the source as native ballerina code
  --exclude, -e    a comma separated list of package names to be filtered from the documentation
  --verbose, -v    enable debug level logs

Usage

Example 1: Generate API documentation for the given Ballerina source directories and files. This would generate API documentation at {currentdir}/api-docs/html/ directory:

$ ballerina doc ../../../connectors/twitter/src/ ../../../connectors/soap/src/ test.bal

Example 2: Generate API documentation for the given Ballerina source directories and files and copy them to the {currentdir}/docs directory:

$ ballerina doc ../../../connectors/twitter/src/ ../../../connectors/soap/src/ test.bal  -o docs

Example 3: Generate API documentation for the given Ballerina source directories and files, excluding org.wso2.ballerina.connectors.twitter package and copy them to the {currentdir}/docs directory:

$ ballerina doc ../../../connectors/twitter/src/ ../../../connectors/soap/src/ test.bal  -o docs -e org.wso2.ballerina.connectors.twitter

Example 4: Generate API documentation for the given Ballerina source directories and files and copy them to the {currentdir}/docs directory while printing debug level logs of Docerina to the STDOUT:

$ ballerina doc ../../../connectors/twitter/src/ ../../../connectors/soap/src/ test.bal  -o docs -v

Example 5: Generate API documentation for the given native Ballerina source directories:

$ ballerina doc ../../../connectors/twitter/src/ ../../../connectors/soap/src/ -n

Using Docerina Maven Plugin

The Docerina Maven plugin is used to generate Ballerina API documentation at the build time of a Ballerina Project.

Introduction

The Docerina Maven plugin is a Maven plugin, which is used within the Ballerina language eco-system. The Maven goals that are achieved through this plugin are explained below:

• docerina: For generating Ballerina API documentation. See the instructions on configuring docerina maven goal.

This goal is executed during the compile phase in the default life cycle of the Maven build. You have the flexibility to configure the behavior of the plugin by passing the relevant parameters to this Maven goal.

Configuring Docerina Maven Goal

A sample pom.xml file configuration of the docerina Maven goal is shown below.

<build>
  <plugins>
      <plugin>
            <groupId>org.ballerinalang</groupId>
            <artifactId>docerina-maven-plugin</artifactId>
            <version>${docerina.maven.plugin.version}</version>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>docerina</goal>
                    </goals>
                    <configuration>
                        <outputDir>${output.dir}</outputDir>
                        <sourceDir>${generated.ballerina.source.directory}</sourceDir>
                        <packageFilter>org.ballerinalang.xyz</packageFilter>
                        <debugDocerina>false</debugDocerina>
                        <nativeCode>false</nativeCode>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Supported list of configuration parameters are listed below;

• sourceDir: Comma separated list of the paths to the directories where Ballerina source files reside or paths to Ballerina files which does not belong to a package. This is a mandatory property. Example: <sourceDir>/home/docerina/abc/src,/home/docerina/xyz/src</sourceDir>
• outputDir: Points to the location where the generated API docs will be stored. This is an optional property and the default value is the ${project.build.directory} which is the target directory. Example: <outputDir>/home/docerina/output</outputDir>
• packageFilter: Comma separated list of package names to be filtered from the documentation. This is an optional property and the default value is is none. Example: <packageFilter>org.ballerinalang.abc.a,org.ballerinalang.xyz.x</packageFilter>
• debugDocerina: Enable debug level logs. This is an optional property and the default value is false. Example: <debugDocerina>true</debugDocerina>
• nativeCode: Treat the source as native ballerina code. This is an optional property and the default value is false. Example: <nativeCode>true</nativeCode>

We invite you to try out Ballerina as well as Docerina and give us your valuable feedback http://ballerinalang.org/#Get-involved.