Update OT CLI Commands

We generate CLI Commands from the CLI source files in the openthread GitHub repository.

This guide provides instructions on how to use our custom Doxygen comments that we use to create the command list.

Get started

To document a CLI command, complete the following steps. It's important that you follow these steps in the order provided.

Find the associated Cmd from the openthread/src/cli directory. For example, to find ba state, search for Cmd("ba"). Each command will have an associated function template:
```
template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
```
In the function template, locate the correct command logic. For example, ba state:
```
else if (aArgs[0] == "state")
```
Before the logic begins, start the @cli Doxygen block:
```
/**
 * @cli ba state
```
Next, immediately below @cli, add examples using @code. Include at least one example. Do not include the > prompt, and make sure to document the full return output, including the standard Done response.
```
 * @code
 * ba state
 * Started
 * Done
 * @endcode
```

Because CLI commands provide command-line access to common API methods and functions, some of the commands share the same description as their corresponding API. If the command description is the same, complete the following steps:

Find the associated API from the openthread/include/openthread directory. For example, ba state maps to otBorderAgentGetState.
Use the api_copy command, then enter the API name directly below it. In front of the API definition, make sure to use the pound sign # to create the automatic Doxygen link.
```
@par api_copy
#otBorderAgentGetState
```

Here's a complete example of the minimum Doxygen comments required to automatically generate an OT CLI command:

/**
 * @cli ba state
 * @code
 * ba state
 * Started
 * Done
 * @endcode
 * @par api_copy
 * #otBorderAgentGetState
 */

To review the HTML output, refer to ba state. For advanced examples and additional options, refer to the following sections.

CLI template options

CLI commands are grouped by one continuous comment block, beginning with the ALIAS tag @cli. Multiple @code examples are supported.

The order you specify each tag is important.

@cparam must come after @code
If you're copying an API description, @par api_copy must come after @cparam

 * @cli command name (overload1,overload2)
 * @code
 * command name arg1
 * Done
 * @endcode
 * @cparam command name @ca{arg1} [@ca{opt-arg}] [@ca{choose-1}|@ca{choose-2}]
 * Optional parameter description; displays below the Parameter heading.
 * *   Markdown and lists are supported.
 * @par api_copy
 * #{apiName}
 * @par
 * Optional CLI specific paragraph. Markdown and lists are supported.
 * @note Notes are supported.
 * @csa{other command name}
 * @sa API method or function name

Next, learn more about how each ALIAS tag is used.

Command names

Any text after @cli becomes the command name header. This header is used in dynamic linking, for example the netdata publish prefix command:

 * @cli netdata publish prefix

Important: Do not use arguments or special characters in command names.

Other commands might be more complex. For example, netdata publish dnssrp unicast provides a few options:

Publish by address and port number
Publish by port number and a device's Mesh-Local EID

If a command is overloaded, use parentheses to uniquely identify the command.

 * @cli netdata publish dnssrp unicast (mle)
 * @cli netdata publish dnssrp unicast (addr,port)

Parameters

Define command parameters using @cparam and @ca.

Put brackets [ ] around optional arguments.
Use vertical bars | (pipes) between argument choices.
To display parameter details, you can enter sentences and markdown lists below the @cparam tag.

Parameters with details

 * @cparam netdata publish prefix @ca{prefix} [@ca{padcrosnD}] [@ca{high}|@ca{med}|@ca{low}]
 * OT CLI uses mapped arguments to configure #otBorderRouterConfig values. @moreinfo{the @overview}.

To review the HTML output, refer to netdata publish prefix.

Parameters with markdown list

 * @cparam netdata show [@ca{local}] [@ca{-x}]
 * *   The optional `-x` argument gets Network Data as hex-encoded TLVs.
 * *   The optional `local` argument gets local Network Data to sync with Leader.

To review the HTML output, refer to netdata show.

Add CLI paragraphs after `@api_copy`

Use @par to add more information to the description. Make sure to drop down to the next line:

 * @par api_copy
 * #otBorderAgentGetState
 * @par
 * CLI description here; add a few things that do not apply to the API method.
 * @par
 * Start a new paragraph.

Description example

 * @par
 * OT CLI checks for `OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE`. If OTBR is enabled, it
 * registers local Network Data with the Leader. Otherwise, it calls the CLI function `otServerRegister`.
 * @moreinfo{@netdata}.

To review the HTML output, refer to netdata register.

Provide CLI-specific description only

Some CLI commands use multiple APIs, or differ from the API call. Others don't have an associated API, for example netdata help. To provide a separate description, use @par. Do not include a @par title, and start your description on the next line. In this scenario, you don't need to use @api_copy.

/**
 * @cli netdata help
 * @code
 * netdata help
 * ...
 * show
 * steeringdata
 * unpublish
 * Done
 * @endcode
 * @par
 * Gets a list of `netdata` CLI commands.
 */

Automatically link APIs

You can link to other API methods or functions with #otFunctionName or @sa. Enter these links at the end of the CLI comment block.

/**
 * @cli netdata unpublish dnssrp
 * @code
 * netdata unpublish dnssrp
 * Done
 * @endcode
 * @par api_copy
 * #otNetDataUnpublishDnsSrpService
 */

Links display in the CLI and API References heading. To review the HTML output, refer to netdata unpublish dnssrp

Preventing automatic links

Sometimes, Doxygen might mistake a normal word as a link to a CLI class, for example, the word Joiner. To prevent Doxygen from linking to keywords or class names used in a sentence, use the % operator in front of the word, for example:

Clear the %Joiner discerner

For more information, refer to Automatic link generation in the Doxygen guide.

Automatically link to other commands

Use @csa to link to other commands.

* @csa{netdata publish dnssrp anycast}

If a command is overloaded, include the parentheses and add a comma if applicable. Don't use spaces inside the parentheses:

* @csa{netdata publish dnssrp unicast (addr,port)}
* @csa{netdata publish dnssrp unicast (mle)}

Doxygen special commands

CLI commands support the following Doxygen ALIASES and special commands:

ALIAS	Example	Description
@cli	@cli ba port	Command name. Starts a CLI comment block.
@code	@code ba port 41953 Done @endcode	Command example.
@ca	[@ca{prefix}]	Command argument. Use brackets `[ ]` for optional arguments.
@cparam	@cparam joiner discerner @ca{discerner} Parameter details.	Command parameters.
@par	@par Optional CLI description.	CLI specific paragraphs.
@csa	@csa{prefix add}	Command See Also. Links to another command.
@sa	@sa otBorderRouterConfig	See Also. Creates a link to an API Reference.
@overview	@overview	Creates a link to the OpenThread CLI Overview.
@netdata	@netdata	Creates a link to Display and Manage Network Data with OT CLI.
@moreinfo	@moreinfo{@netdata}	Creates a referral link.
@note	@note Important callout.	Creates a note callout box.

Update OT CLI Commands

Get started

CLI template options

Command names

Parameters

Parameters with details

Parameters with markdown list

Add CLI paragraphs after @api_copy

Description example

Provide CLI-specific description only

Automatically link APIs

Preventing automatic links

Automatically link to other commands

Doxygen special commands

Add CLI paragraphs after `@api_copy`