Generate code documentation

Ballerina has a built-in Ballerina Flavored Markdown (BFM) documentation framework named Docerina. The documentation framework allows you to write unstructured documents with a bit of structure to generate HTML content as API documentation.

Generate documentation for modules

Developers can write the documentation in line with the Ballerina source code using the lightweight markdown markup language. They can document special constructs such as parameters, return values, fields, etc., within the code using documentation attributes. Once the code is documented, developers can generate a basic HTML version of their Ballerina modules using the bal doc command. Developers are encouraged to have their custom themes and styles, to have a standard presentation of their Ballerina documentation.

Ballerina documentation design and usage is aligned with the package and module semantics of Ballerina. You can generate documentation for modules using the bal doc command.

  • Ballerina programmers can place the documentation in line with the source code using the documentation syntax.
  • Ballerina type definitions, global variables, annotations, listeners, etc., can be documented using the documentation syntax.
  • Fields, parameters, return values, etc., can be marked using documentation attributes.
  • Ballerina uses a React app to render the documentation, and the data required is stored as a JSON in the api-docs.js file. The React app source code can be found in the ballerina-dev-tools GitHub repo. Developers are welcome to customize and try out themes and styles in the React app.

Write Ballerina documentation

Ballerina Flavored Markdown documentation is a first-class syntax in the Ballerina language. The # at the beginning of a line denotes a line of documentation. If necessary, you can have multiple lines of documentation, which you can group together.

When writing the documentation for Ballerina APIs, you can use the standard markdown documentation syntax as shown below.

The supported structure of documentation syntax is as follows:

Tip: Always add a period (.) at the end of a function description. However, for the parameter and return type descriptions, omit the period if you have only one sentence. If there are multiple sentences, add the period at the end of each sentence. For example,

Sample usage

Document a module

A Ballerina module can have a Module.md file, which describes the module and its usage.

A typical package structure of a Ballerina package is like this:

/
  Ballerina.toml       # Configuration, which defines the package intent.
  main.bal
  Module.md            # Contains descriptive metadata of the default module to be displayed in
                       # API documentation. This is optional.
  Package.md           # Contains descriptive metadata of the package to be displayed in
                       # Ballerina Central. This is optional.
    modules
      module1/             
        Module.md      # Contains descriptive metadata to be displayed in 
                       # Ballerina Central. This is optional.
        *.bal
        [tests/]       # Module-specific unit and integration tests.
        [resources/]   # Module-specific resources.

      module2/
        Module.md
        *.bal
        [tests/]
        [resources/]

  [resources/]         # Resources included in every module in the package.

  target/              # Compiled executables and other artifacts end up here.

The bal doc command will read the Package.md and Module.md files and prepend them to the generated HTML file.

Check the http module API Documentation for sample HTML that has Module.md content at the top followed by the other module constructs.

Generate Ballerina documentation

Ballerina provides a doc command, which can be executed against a given Ballerina package. This command will result in generating the Ballerina documentation as HTML files for all the modules in the package.

First, let's create a new Ballerina package:

$ bal new math
Created new Ballerina package 'math' at math
$ tree
└── math
    ├── Ballerina.toml
    └── main.bal

1 directory, 2 files

Now, let's add a function to the math module to be documented. Copy and paste the following code into the math/main.bal file.

Now, navigate to the math directory, and run the bal doc command to generate the documentation of the package.

$ cd math
$ bal doc

Output:

Compiling source
	user/math:0.1.0
Generating API Documentation
Saved to: apidocs

target/apidocs/user/math/0.1.0 folder would contain the following;

$ ls target/apidocs/user/math/0.1.0/
bundle.js  index.html  ...
  • index.html - the entry point for documentation

For other options, run bal doc --help.