Tags

Here are some tags that can be used in the code as comments and it will be automatically parsed and included in the documents.

@name

Title of the documented page that will be displayed as a link on the main index page.

/# @name sample Sample functions to demonstrate the usage of tags for document generation

@package

Logical group name, it can be used to with multiple files (@name). This will be used for grouping the various @name under the same @package name on the index page.

/# @name sample Sample functions to demonstrate the usage of tags for document generation
/# @package example

@desc

Explanation of the function, package, parameters etc. it will be used as paragraph when the documents are generated. Any comment without any tag will also be considered as @desc.

/# @desc  Stores the trades

or

/# Stores the trades

@function

Name of the function displayed as document section title. The rest of the content will be displayed as a paragraph.

/# @function foo A sample function to generate 
/#. an inline table for input parameter dictionary

@code

Literal code block to be displayed on the generated documents.

/# @code show dict

@eval

The code after this tag will be executed and output will be shown on the generated document.

/# @code-eval " func2[2;3] = ", string 2+3

@param

Input Parameter to the function

/# @param x  Input Parameter x   
/# @param y  Input Parameter y   

@return

The output returned by the function

/# @return int sum of x & y

@header

Table header; the columns can be defined using a pipe (e.g. Col1|Col2|Col3). It can be used with or without schema tag.

/# @header Key|Type|Required|Default|Desc

@row

Table row; cells are | (pipe) separated.

/# @row    startDate|date|0b|.z.d|Start Date  (if null or not provided, will be set as current date)
/# @row    endDate|date|0b|startDate|End Date (if null or not provided, will be set as start date)

@todo

Something to be done

/# @todo Change the function name?

@schema

To specify a schema definition, the formatting of this tag is similar to the @function tag; should be used with @header and @row

/# @schema tab
/# @header Column Name|Type|Desc
/# @row d |date  |Trade Date
/# @row t |time  |Trade Time

@toggle

Show/Hide the contents.

/# @toggle Calculate the sum

@bullet

The content followed by this tag will be displayed as a bullet point in the documentation.

/# @bullet Text Style test
.unittest.assert[`.rest.ts; ("italics";"*") ;"*italics*"];
/# @bullet Italics test
.unittest.assert[`.rest.i; enlist "italics" ;"*italics*"];

@error

To Display an error message explicitly. The same formatting is used to report an error while processing the tags.

/# @error Throws an error when an input is not numerical 

@see

/# @see  lib-str

@tags

It can be used to define the keywords that can be found by browsing.

/# @package lib
/# @name rest Sphinx-ReST helper functions to generate the ReST documents.
/# @tags sphinx