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.jsfile. The React app source code can be found in the
ballerina-dev-toolsGitHub 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,
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.
bal doc command will read the
Module.md files and prepend them to the generated HTML file.
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
Now, navigate to the
math directory, and run the
bal doc command to generate the documentation of the package.
$ cd math $ bal doc
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.