Doc-Comment Structure
4 min read
4 min read
4 min read
4 min read
4 min read
4 min read
4 min read
4 min read
4 min read
A doc comment typically starts with a short description, continues with any further details, and ends with block tags that document specific parts of the definition. A block tag starts a line with @, and its text continues until the next tag or the end of the comment:
/// Looks for an item with the specified primary and secondary keys./// Keys are compared case-sensitively./// @param p The primary search key./// @param s The secondary search key./// @return The item that matches the specified keys./// @throws NotFound Thrown if no item matches the specified keys./// @see ItemItem findItem(Key p, Key s) throws NotFound;The inline tags {@link identifier} and @p name go within the text; see Formatting and Links.
Every Slice compiler except slice2php and slice2rb checks each doc comment against the rules on this page: it warns about a tag it doesn't recognize, and ignores it.
Formatting and Links
Text between backticks is code, and the compilers format it as code in each language:
/// Returns `true` if the catalog holds no items.bool isEmpty();To write a backtick that does not start code, escape it with a backslash.
{@link identifier} links to another Slice definition. The compilers look up the identifier like any Slice name, from the scope of the documented definition, and warn when it names nothing. Catalog#findItem links to the member findItem of Catalog, and #findItem to a member of the documented type:
/// Holds the items of a store. Use {@link #findItem} to look one up.interface Catalog@p name refers to the operation's parameter name, which the compilers format as code. It is valid only in an operation's doc comment:
/// Looks for the item whose primary key is @p p and whose secondary key is @p s.Item findItem(Key p, Key s) throws NotFound;The compilers warn about a {@link} or @see tag that names a parameter.
General Tags
You can use the following tags in any doc comment.
@see identifier
@see identifierAdds a cross-reference to another Slice definition, which the compilers look up as they do for {@link}. Each @see tag holds one identifier, on a line of its own and with no trailing period:
/// Thrown when no item matches a search./// @see Catalog#findItemexception NotFound {}@remark / @remarks
@remark / @remarksStarts a remarks section, for details that don't belong in the description.
@deprecated
@deprecatedDocuments that the definition is deprecated. The text after the tag says why, or what to use instead. Use this tag together with the deprecated metadata directive, which marks the definition as deprecated.
Operation Tags
You can use the following tags only in an operation's doc comment. The compilers warn about them anywhere else, and ignore them.
@param name
@param nameDocuments the parameter name, which must be an in or out parameter of the operation.
@return
@returnDocuments the return value. The compilers warn about @return on an operation that does not return a value.
@throws name / @exception name
@throws name / @exception nameDocuments when the operation throws the exception name, which must appear in the operation's exception specification. The two tags are equivalent.
Document each parameter, exception, and return value once: the compilers warn about a duplicate tag, and ignore it.