31  Documentation

org.arl.fjage.shell.Services.DOCUMENTATION

31.1 Overview

The DOCUMENTATION fjåge service enables a Unet agent to hook into the fjåge help system and provide documentation to the user. Any agent — including the ones you write (Chapter 33) — can register this service to make its parameters and commands discoverable through help on the shell. The reference tables in this part of the handbook are generated from this very documentation.

31.2 Messages

This service defines no messages. The help system reads the documentation through the standard parameter messages, by querying the __doc__ parameter described below.

31.3 Parameters

An agent providing the DOCUMENTATION service exposes the following unlisted read-only parameter:

  • __doc__ – documentation string

The documentation string should be in markdown format with up to 3 heading levels. The top-level heading should provide a section title. Second-level headings may demarcate different categories of documentation (e.g. messages, commands, or parameters). Third-level headings are used to document individual commands or parameters. The placeholder @@ may be used to denote the agent name. This avoids the need for dynamically generating documentation at runtime by looking up the agent name.

Although the markdown triple-tick fenced code blocks work, they are not well suited for help display on the terminal. Instead of using them, it is recommended that code blocks are indented by one (or more) spaces. A block of indented lines is automatically treated as if it were a fenced code block.

Documentation may be cached by the help system for performance. To disable caching (if the documentation is dynamic), the documentation string must start with [no-cache].

Tip

For an agent to expose a read-only parameter __doc__, all it needs to do is to have a public final static String attribute called __doc__ in the agent class. If the documentation is to be dynamically generated, a public String get__doc__() method may be used instead. To ensure that the parameter is unlisted, it should not be included in the list returned by the getParameterList() method call.

31.4 Examples

A typical documentation style is illustrated below:

# @@ - my special link agent

My special link agent demonstrates how documentation should be written.

Services provided: LINK

## Parameters:

### @@.phy - physical layer agent name
### @@.retries - maximum number of retries

Retries are only relevant for reliable datagrams.

Examples:
 @@.retries = 3           // change the number of retries to 3
 @@.retries               // check the current number of retries

### @@.batchSize - number of frames to send in each batch

## Commands:

My special link agent provides no commands.

31.5 Implementations

Most agents in the default stack provide this service — that is how their help entries, and the parameter tables in this handbook, are produced. There is no dedicated agent: any agent that exposes a __doc__ string and registers org.arl.fjage.shell.Services.DOCUMENTATION is a provider.

The same __doc__ convention (and format) is used by shell extensions to document the commands they contribute — see Section 33.7.