Version: 🚧 Alpha 🚧

Generation of the documentation

The GAMA documentation is made of the pages of the GAMA wiki, which are also published on the GAMA website. Most pages are written by hand, but the GAML reference (operators, statements, skills, architectures, built-in species, constants and units, index of keywords, extensions) is generated from the Java sources and their annotations. This page explains how this generation works, and how to document Java code so that it appears correctly in the reference.

Overview

flowchart TD
    J["Java sources + annotations<br/>(@operator, @symbol, @skill, @doc, @example, @test...)"]
    P["gama.processor<br/>(annotation processor, at compile time)"]
    X["docGAMA.xml per plugin<br/>gaml/ (Eclipse) or target/ (Maven)"]
    T["Generated test models<br/>gaml/models/Tests/Generated From ..."]
    U["gama.documentation: MainGenerateWiki<br/>merge into files/gen/java2xml/docGAMAglobal.xml"]
    W["gama.wiki clone<br/>References/GAMLReferences/*.md, WikiOnly/Operators*.md,<br/>Exhaustive-list-of-GAMA-Keywords.md, References/PluginDocumentation/*.md"]
    R["files/gen/prism/prism-gaml.js"]
    S["GAMA website<br/>(gama-platform.github.io)"]
    G["prism-gaml repository"]
    J --> P
    P --> X
    P --> T
    X --> U
    U -->|XSLT| W
    U -->|XSLT| R
    W --> S
    R --> G

At compile time, the annotation processor gama.processor (class gama.processor.doc.DocProcessor) reads the GAML annotations of each plugin and writes a docGAMA.xml file describing its operators, statements, skills, architectures, species, types, files and constants. In Eclipse, it is written in the generated folder gaml/ of the plugin (next to gaml/additions/<shortcut>/GamlAdditions.java); in a Maven build, in the target/ folder of the plugin.
The processor also emits warnings for undocumented elements (GAML: documentation missing for ...) and untested operators (GAML: operator '...' is not tested), and generates test models from the @test annotations (and fuzz tests) in gaml/models/Tests/Generated From <Plugin>/models/.
The generator of the gama.documentation project merges the docGAMA.xml files and transforms them into wiki pages with XSL stylesheets.

The `gama.documentation` project

Path	Content
`src/gama/documentation/MainGenerateWiki.java`	Main class generating the wiki pages (see below).
`src/gama/documentation/MainGenerateLLM.java`	Variant that only produces `files/gen/gen-LLM-gaml.md`, a condensed description of the operators for language models.
`src/gama/documentation/util/Constants.java`	All the paths used by the generator (input, output, wiki location).
`src/gama/documentation/util/UnifyDoc.java`, `WorkspaceManager.java`	Selection and merge of the `docGAMA.xml` files.
`src/gama/documentation/transform/XmlToWiki.java`	Transformation into markdown pages.
`files/input/xsl/`	XSL stylesheets: `xml2md` (wiki pages), `xml2prism` (syntax highlighting), `xml2keywordsXml`, `xml2test`, `xml2json`, `xml2docLLM`.
`files/gen/`	Intermediate and generated files (ignored by Git).

MainGenerateWiki performs the following steps:

Prepare the folders: deletes and recreates files/gen/, and creates the output folders in the wiki clone. Note that it also deletes gama.library/models/Tests if it exists.
Merge the documentation: only the plugins reachable from the features of gama.product/gama.product are taken into account. Their docGAMA.xml files are merged into files/gen/java2xml/docGAMAglobal.xml. Without argument, the files are read from the gaml/ folders (Eclipse build); with the -online argument, from the target/ folders (Maven build).
Generate the wiki pages in the wiki clone:
- References/GAMLReferences/: Operators.md, OperatorsSplitted.md, Statements.md, BuiltInSkills.md, BuiltInArchitectures.md, BuiltInSpecies.md, UnitsAndConstants.md, UnitsAndConstantsPDF.md;
- WikiOnly/: OperatorsAA.md, OperatorsBC.md, OperatorsDH.md, OperatorsIM.md, OperatorsNR.md, OperatorsSZ.md;
- Exhaustive-list-of-GAMA-Keywords.md at the root of the wiki;
- for the plugins that have a target/docGAMA.xml but are not part of the product (extensions), References/Extension.md and one References/PluginDocumentation/Extension_<plugin>.md per plugin.
Generate files/gen/prism/prism-gaml.js, the GAML grammar for the Prism syntax highlighter used by the website.
Update the LaTeX style files/input/pandocPDF/gama_style.sty from the keywords.xml file of the wiki, if present. The generation of keywords.xml itself (XmlToCategoryXML) is currently disabled in MainGenerateWiki.

The generated pages start with a warning saying that they are generated: never edit them by hand, modify the Java documentation instead.

Automatic regeneration

The documentation is regenerated by the GitHub Actions workflow "Documentation Auto Refresh" (.github/workflows/trigger-doc-regeneration.yaml), every Saturday or on manual dispatch. It:

builds GAMA with Maven (travis/build.sh) on JDK 25;

clones the wiki next to the GAMA clone and runs, from gama.documentation:

java -cp ".:libs/jdom-2.0.1.jar:target/classes:../gama.annotations/target/classes" gama.documentation.MainGenerateWiki -online

commits and pushes the modified wiki pages (as GAMA Bot), if any;
triggers the rebuild of the website (gama-platform.github.io);
pushes the new prism-gaml.js to the prism-gaml repository.

Generating the documentation locally

To check how your documentation will look before it is published:

Clone the wiki next to your GAMA clone (the generator writes into ../gama.wiki relative to the root of the GAMA repository, see WIKI_FOLDER in Constants.java):
```
git clone https://github.com/gama-platform/gama.wiki.git
```
Build GAMA, either in Eclipse (GAMA > Clean GAMA plugins, which produces the gaml/docGAMA.xml files) or with Maven (which produces the target/docGAMA.xml files, see Creating a release of GAMA).
Run gama.documentation.MainGenerateWiki as a Java application, with gama.documentation as working directory (all paths are relative to it). Pass -online if you built with Maven. Note that the extension pages are always produced from the target/docGAMA.xml files.
Review the changes in the wiki clone with git diff. The official pages are regenerated by the workflow above: do not push generated pages by hand unless asked to.

How to document the Java code

The generator only uses the information produced by the processor: the GAML annotations and, for operators, the signature of the Java methods. See the index of annotations for the complete list.

The `@doc` annotation

Most annotations (@operator, @symbol, @skill, @facet, @variable, @action, @arg, @species, @type, @file, @constant...) are accompanied by, or contain, a @doc annotation. For example, the inter operator is documented in gama.core/src/gama/gaml/operators/Containers.java:

@operator (
		value = "inter",
		can_be_const = true,
		content_type = ITypeProvider.CONTENT_TYPE_AT_INDEX + 1,
		category = IOperatorCategory.CONTAINER,
		concept = { IConcept.CONTAINER })
@doc (
		value = "the intersection of the two operands",
		comment = "both containers are transformed into sets (so without duplicated element, cf. remove_deplicates operator) before the set intersection is computed.",
		usages = { @usage (
				value = "if an operand is a graph, it will be transformed into the set of its nodes"),
				@usage (
						value = "if an operand is a map, it will be transformed into the set of its values",
						examples = { @example (
								value = "[1::2, 3::4, 5::6] inter [2,4]",
								equals = "[2,4]"),
								@example (
										value = "[1::2, 3::4, 5::6] inter [1,3]",
										equals = "[]") }),
				@usage (
						value = "if an operand is a matrix, it will be transformed into the set of the lines",
						examples = @example (
								value = "matrix([[3,2,1],[4,5,4]]) inter [3,4]",
								equals = "[3,4]")) },
		examples = { @example (
				value = "[1,2,3,4,5,6] inter [2,4]",
				equals = "[2,4]"),
				@example (
						value = "[1,2,3,4,5,6] inter [0,8]",
						equals = "[]") },
		see = { "remove_duplicates" })
@tests ({ @test ("[1,2,3,4,5,6] inter [0,8] = []"), @test ("[1, 2, 3] inter [2, 3, 4] = [2, 3]") /* ... */ })

The attributes of @doc are:

Attribute	Use
`value`	Main description of the element.
`comment`	Additional comment.
`usages`	Particular ways of using the element, each one a `@usage` with a description (`value`) and `examples`.
`examples`	Examples not related to a particular usage (`@example`).
`see`	Related GAML keywords.
`returns`, `special_cases`, `side_effects`	Return value, special cases and side effects.
`deprecated`	Marks the element as deprecated, with an explanation.
`masterDoc`	When an operator has several Java implementations, designates the one carrying the main documentation.

The `@example` annotation

An @example contains an expression (value) and, optionally, its expected result (equals, or isNot, or raises for an expected error/warning), for example @example (value = "[1::2, 3::4, 5::6] inter [2,4]", equals = "[2,4]"). In the documentation, the example is shown as GAML code assigning the expression to a variable (named by var, or generated), together with its expected value; returnType gives the type of this variable when it cannot be inferred. Other attributes:

Attribute	Default	Meaning
`isExecutable`	`true`	`false` if `value` cannot be compiled on its own (for instance when it refers to species that are not defined).
`test`	`true`	Whether the result is compared to `equals`.
`isTestOnly`	`false`	`true` to use the example for testing only, without showing it in the documentation.
`isPattern`	`false`	Marks the example as a pattern.

Tests

Operators should also be tested with @test (or @tests for several), which contain GAML boolean expressions, as in the example above. If an operator cannot or need not be tested, annotate it with @no_test (with a Reason, for instance Reason.ALREADY_TESTED or Reason.IMPOSSIBLE_TO_TEST).

What is used for each kind of element

Operators (Java methods annotated with @operator, mostly in gama.core/src/gama/gaml/operators): the names (value, the first one being the main name, the others alternative names), category and concept of @operator; the @doc; the return type and the parameter types of the method (the IScope parameter is ignored).
Statements (classes annotated with @symbol, mostly in gama.core/src/gama/gaml/statements): the @symbol, the @facets (each @facet having its own doc), the @inside annotation (where the statement can be used) and the @doc.
Skills (classes annotated with @skill, mostly in gama.core/src/gama/gaml/skills): the @skill, the @vars (each @variable having its own doc), the @actions (with their @args) and the @doc.

Tools to complete the documentation

The GAMA Developer Tools help to find undocumented elements:

the processor warnings get quick fixes (Ctrl/Cmd+1 in the Java editor or the Problems view): Add a @doc skeleton, Add a @test skeleton (to complete), Mark as @no_test(...), or Generate a GAML test stub;
GAMA > Report > Missing annotations builds a Markdown report of the undocumented elements and untested operators, per plugin;
GAMA > Repair GAMA plugins > Generate missing tests writes models/Tests/Untested Operators.gaml in the selected plugins.

Modifying the processor

If you modify gama.processor or gama.annotations, regenerate the processor JAR used by Eclipse (gama.processor/gama.processor.jar) with GAMA > Repair GAMA plugins > Rebuild annotation processor, then run GAMA > Clean GAMA plugins to regenerate all the gaml/ folders. Maven builds compile the processor from its sources (it is a module of gama.parent).

Overview​

The gama.documentation project​

Automatic regeneration​

Generating the documentation locally​

How to document the Java code​

The @doc annotation​

The @example annotation​

Tests​

What is used for each kind of element​

Tools to complete the documentation​

Modifying the processor​