Good API documentation is one of the many factors contributing to the overall success of a software project. Fortunately, SARL provide a tool for generating API documentation from comments present in the source code.
Because the SARL compiler generates Java code, the SARL documentation tool is based on the famous Javadoc tool. Javadoc is a documentation generator created by Sun Microsystems (now Oracle) for the Java language for generating API documentation in HTML format from Java source code. The HTML format is used for adding the convenience of being able to hyperlink related documents together.
The “doc comments” format used by Javadoc is the de facto industry standard for documenting Java classes. SARL uses the same standard format.
Documentation does not affect performance in neither in SARL not Java as all comments are removed at compilation time. Writing comments and documentation is for better understanding the code and thus better maintaining it.
Javadoc also provides an API for creating doclets and taglets, which allows users to analyze the structure of an application. This enables to generate specific documentation pages.
SARL comes with a specific doclet that replaces all the elements written with the Java syntax by their equivalent into the SARL syntax. The SARL doclet is provided into the Maven module:
io.sarl.docs
io.sarl.docs.doclet
See the next sections for details on the usage of the SARL doclet.
The Maven Javadoc Plugin uses the Javadoc tool to generate documentation for the specified project. The Maven Javadoc Plugin gets the parameter values that will be used from the plugin configuration specified in the POM file.
To generate output from an alternate doclet, add configuration similar to the following to your POM file.
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<doclet>io.sarl.docs.doclet.SarlDoclet</doclet>
<docletArtifact>
<groupId>io.sarl.docs</groupId>
<artifactId>io.sarl.docs.doclet</artifactId>
<version>${sarl.version}</version>
</docletArtifact>
</configuration>
</plugin>
</plugins>
</build>
As described into the Javadoc documentation,
the javadoc command has options for doclets.
The Javadoc command provides -doclet
option for specifying a custom doclet.
A typical command-line to launch is:
javadoc -doclet io.sarl.docs.doclet.SarlDoclet
-cp doclet-0.14.jar:path_to_sources
-source 1.8
-sourcepath path_to_sources
-d path_to_documentation
In order to use the SARL doclet, you have to specific the name of the doclet with the -doclet
.
You must also include the SARL doclet binary file into the class path with the -cp
.
In the example above, the name of the SARL doclet’s jar file is doclet-[:sarl.specification.release_version!].jar
.
The SARL doclet provides specific options that may be used into the documentation text itself, or from the command-line.
The SARL doclet has the same options as the Standard doclet.
It is possible to exclude elements from the documentation by adding the @ExcludeFromApidoc
into the SARL documentation. For example:
/** This is an example of excluded documentation.
*
* @ExcludeFromApidoc
*/
class TheClass {
}
Copyright © 2014-2024 SARL.io, the Original Authors and Main Authors.
Documentation text and medias are licensed under the Creative Common CC-BY-SA-4.0; you may not use this file except in compliance with CC-BY-SA-4.0. You may obtain a copy of CC-BY-4.0.
Examples of SARL code are licensed under the Apache License, Version 2.0; you may not use this file except in compliance with the Apache License. You may obtain a copy of the Apache License.
You are free to reproduce the content of this page on copyleft websites such as Wikipedia.
Generated with the translator docs.generator 0.14.0.