Documentation

NPL supports a subset of JavaDoc. This JavaDoc can then be displayed in the plugin.

A JavaDoc is a specially crafted comment immediately preceding the documented entity. The documented entity can be one of function, protocol, symbol, permission, obligation, struct, and identifier. To display the documentation, position the caret at an identifier, and select View | Quick Documentation.

The format of JavaDoc is as follows:

/**
 * The Javadoc starts with '/**' followed by an empty line.
 * The description of the element at hand follows. The description can
 * be split to multiple lines for clarity.
 *
 * Also, it may contain multiple paragraphs.
 *
 * After the description comes the tag section. Each tag begins with '@'
 * followed by the tag name. The current items are
 *
 * @param x    describes the function/permission/obligation/protocol parameter x
 * @param y    describes the parameter y. Similarly to above, its description can
 *             be split to multiple lines.
 * @party p    documents the signing party of a protocol or an allowed party for an action
 * @field f    describes a field of a struct declaration
 * @return Description of the return value of a function/permission/obligation.
 *         There may be only one @return tag. */

The Quick Documentation also shows the signature of the symbol, e.g. parameters, return type, applicable states. All elements in the Quick Documentation view are navigatable, and the link leads to documentation of the target symbol. Navigating backwards and forwards in the documentation window history can be done using hotkeys '<-' and '->'. To open the editor on the source of the current symbol, press F4. The signature itself can also be displayed using Cmd+hover.

Press Ctrl + N (or right click, Generate) when the caret is at declaration (struct, identifier, protocol, symbol, action, function, notification). Then, select " documentation". This will create a skeleton of a documentation for the given declaration, along with all suggested tags (e.g. @param for each function parameter). If the documentation is already present when you do this, it is reformatted - the order of tags is fixed, missing tags are added, and the whitespace is corrected.