Anvildoc

Anvil scripts and templates may be commented using java-style @tags.

In scripts the syntax of comment is following:

 /**
  * Sets the name of user.
  * @synopsis void setUser(User user)
  * @param user User object
  * @author zorg
  */
 function setUser(user) { ... }

In Templates the syntax of comment is following:

 <!--/**
      *  Shows the user's information.
      *  @param user User object
      *  ...
      */-->
 <function name=showUser param=user>...</function>

Preceding asterisks (*), and those found in start of individual lines are discarded.

Comments may be attached into modules, namespaces, classes, interfaces, functions, constants and variables. Attaching meaning that some document comment precedes the declaration of entity, though whitespaces are allowed between.

Following tags may appear in scripts, templates and Java libraries:

@attribute identifier text

This tag cannot be used standalone, instead it may appear as a part of class's documentation. It is used to comment different attribute accesses (self.attrname) to instances of class in question.

@author text

Adds an comment indicating the author of entity. There may be multiple author tags.

@category text ¹

Specifies logical "category" for target entity.

@default text

Add a comment about default value of parameter, this tag may only be used with @param tag.

@deprecated text ¹

Adds a comment indicating that this API should no longer be used (even though it may continue to work).

@exclude ¹

Specifies that this entity should not be shown in document browser.

@obsolete text ¹

Adds a comment indicating that this API should no longer be used (it does nothing).

@operator identifier text

This tag cannot be used standalone, instead it may appear as a part of class's documentation. It is used to comment behaviour that different operators have when used to instances of class in question.

@param identifier text

Adds a parameter to the "Parameters" section.

@reference identifier text

This tag cannot be used standalone, instead it may appear as a part of class's documentation. It is used to comment different reference accesses (self[expr]) to instances of class in question.

@return text

Adds a "Returns" section with the description text. This text should describe the return type and permissible range of values.

@see text

Provides a link to some related part of documentation.

@since text

Describes the version since when this entity has been available.

@synopsis text

Add a synopsis text which shortly summarizes the use of entity (most functions). If text contains semicolon (;) then the text is split to two parts so that left side becomes the actual synopsis and the right side is description for that. There may be multiple of these tags.

@throws identifier text

Indicates that some exception may be thrown in some circumstances.

@type text

Describes the type of parameter, this tag may only be used with @param tag.

@version text

Decribes the version of the API, etc.

@define identifier text

Adds a parameter for function or method. Parameters defined may be fetched with respective identifier names from anvil.runtime.Function and anvil.runtime.Type. The return type of identifiers is always anvil.runtime.string.

1) Tag is not used by the document browser

If tag has an identifier it may optionally be enclosing with double quotes (") this giving the possibility to include whitespaces into identifier.

Following tags may only appear in native java libraries, where they are required for establishing the context of documentation.

@class identifier text

@const identifier text

@constructor identifier text

@function identifier text

@interface identifier text

@member identifier text

@method identifier text

@module identifier text

@namespace identifier text

@var identifier text

Add a note