Special tags


In this chapter, you can find information about:

Index of special tags

Here are the special tags in Cod2Doc (all tags are case insensitive):


Adding more description

There is a lot of special tags which accept only one line of description by default. To add more line of description to these tags, you should add the ;+ tag just below the tag you want to describe. Description of variables (constant, global, array, field) as well as variable and return value description in the function description may use the ;+ tag.
The ;;+ tag has the same functionality, but it has the particularity to continue the previous line (no carriage return).

The following tags accept the ;+ or ;+ tag: ;author, ;bug, ;cell, ;creation, ;group, ;lastUpdate, ;project, ;table, ;toDo, ;version.

Example:
Global variable1  ; Description of the variable
                  ;+ some more description
;bug One bug
;+ more description of this bug
;+ Another bug


Project tags

Structure:
;author Description of the author
;bug Description of the bug
;creation Date of creation
;lastUpdate Date of last update
;project Description of the project
;toDo Description of the to-do list
;version Description of the version

Project tags are here to document your code in a standardized way. They can be inserted in the header of the code, in the inline documentation, in the Type or Function description. The following tags are available: The description of project tags can be extended using the ;+ tag. The text resulting of the tag can be changed with the modification of the language file (see here).

Result:

Author:
Description of the author
Bugs:
Description of the bug
Creation:
Date of creation
Last update:
Date of last update
Project:
Description of the project
To do:
Description of the to-do list
Version:
Description of the version



Code tags

The code tags are very useful when you want to show some Blitz Basic code in your documentation (or even other types of code). The code will be highlighted as it is in your usual IDE (unless you specify the option Do not highlight code in the graphical interface).
Notice that the code tags could be used in the function or type description as well as in the inline documentation.


The ;example tag:

Structure:
;example
; Some code
;/example

;example fileName.bb
; Some code
;/example

If you insert these tags into a description, all the code located between the ;example and ;/example tags will turn into code. The "Example:" text turns to a link to a Blitz Basic file containing the code.

If no file name is specified after the ;example tag, then the code will be saved in a file with the same name of the function it is located (if it's inside a function description). If a file name is specified, then the code will be saved in this file. The files are saved in the subdirectory files\ of the documentation directory (Cod2Doc\ by default). You can precise a relative path in the fileName. Warning: if a file with the same name exists, it will be erased!

If you don't want to save this piece of code, simply write ";example -" or ";example !" (only useful inside a function description).
For alignment reasons, in the code region, you have to let always one space after the first ";"!

Notice also that having some html tags in you code can cause big problems. Try to avoid this situation!

Example:

Example:
; Type the ;example tag inside the description of the function
;example
; ; This an example of how this function works
; For i = 1 to 10
;   FunctionExampleCode()
; Next
;/example
Function FunctionExampleCode()
End Function

This gives the result:

FunctionExampleCode()
Description:
Type the ;example tag inside the description of the function
Return value:
None
Example:
; This an example of how this function works
For i = 1 To 10
  FunctionExampleCode()
Next



The ;code tag:

Structure:
;code
; Some code
;/code

;code fileName.bb
; Some code
;/code

;code[Description string] fileName.bb
; Some code
;/code

This tag is quite similar to the previous one, and actually extends the ;example tags. The only difference is that you can specify the string that you want to write for the code description (instead of "Example:" for the ;example tag). To precise the description string, you just put this string into [] after the ;code tag (without space). For example ";code[A wonderful piece of code:]". If no [] are used, then the default string is "Code:". If you don't want to have a description string at all, just put ";code[]".
See the ;example tag for other details as everything is similar otherwise.


Tags to import code from a file:

Structure:
;importCode fileName.ext

;importCode[Description string] fileName.ext

;importExample fileName.ext

These tags are used to import code from a given file. The file will be cut and past and put at the place of the tag. If the file is a Blitz Basic file, then the code will be highlighted.

For the ;importExample tag, the description string will be "Example:". For ;importCode, it will be "Code:" unless you specify into brackets the description string. If no description string is precise between the [], then there will be no description string at all.

Example:

Example:
;importCode[Example of imported code:] ExampleImportedCode.bb

This gives the result:

Example of imported code:
; This is a small example of an imported code

Repeat
  Print "Press Esc to quit this!"
Until KeyHit(1)



Groups

Structure:
;group Optional description of the group
Some keywords...
;/group

Sometimes it is useful to group your variables or your functions together in the documentation (for variables related to the same functionality for example). The behaviour of the group depends on the layout set in the main window:
Warning: groups can not contain another group!
Warning: the ;group tag shouldn't be placed inside description of type or function!

Groups can also be created in the inline documentation (the above rules do not apply). Groups in the main program and in the inline documentation are independent and could be inserted in each other.
You can also add a description of the group (and more description with the ;+ tag) by adding a text after the ;group tag.

Example:
;group
Const constant1 = 1
Const constant2 = 2
Const constant3 = 3
;/group

;group Description of the group
;+ more description of the group
Global global1
Global global2
;/group


Defining the end of the header

Structure:
;endHeader

This tag could be useful in some occasion to mark the end of the header of the file. The only use of this tag is when you use an inline documentation and you want to differentiate the inline documentation contained in the header and the one related to the first variable.


Veto

There is several ways to put a veto to avoid documentation.


Veto for a line of comment:

Structure:
;! This line won't be documented
;;+! This line neither
;!+ This line neither
;! This line neither
;;+! This line neither

These tags may be used to avoid inserting a commented line in your documentation (technical comments for example). Of course, there is no need to veto comments in the program which are not taken into account by Cod2Doc!


Veto for code (variables, functions, ...)

Structure:
Global myVar ;!! This variable won't be documented

Function myFunc ;!! This function won't appear in the documentation
End Function

Type myType ; This type will be documented
  Field field1 ; This field will be documented
  Field field2 ;!! This field won't be documented
End Type


Sometimes, you don't want that some variables/functions (technical ones for example) appear in the documentation. To do that, simply add the tag ;!! anywhere on the line you don't want to document. Adding this tag on the line of the declaration of a function or of a type will of course prevent the whole function/type to appear in the documentation. This tag could be used for variables, arrays, types, fields, functions, ...


Veto for a group of line of code:

Structure:
;noDocumentation
Global myVar ; This line won't be documented
; This line and the function won't be documented either
Function myFunc
End Function
;/noDocumentation

Simply add a ;noDocumentation tag ended by the ;/noDocumentation tag. Any code/comments inbetween these two tags won't be documented.


Veto for a single word:

If you don't want that a word turn into automatic link, or automatic inserted image, then a ! has to be placed in front of the word (See also: automatic links).


"See also:" tag

Structure:
;see some text
; Some text. ;see some other text

The ;see tag may be inserted in every description comments. It will simply be replaced by the "See also:" string (with a specific style defined in the style file). This tag may be located at the first position in the comment or anywhere in this comment.

You have also the possibility to use the ;+see tag instead of the ;+ prolongation tag. The ;;see and ;;+see tags are also supported.

Example:

Example:
Global myVariable% ;see myOtherVariable%
Global myOtherVariable% ; Some description here. ;see myVariable%

This gives this result:

myVariable%
Description:
See also: myOtherVariable%


myOtherVariable%
Description:
Some description here. See also: myVariable%



Tags for the html header (title, keywords)

Html title:

Structure:
;htmlTitle Title of the documentation

This tag allows you to define the title of the html file. This title appears at the top of the browser as well as in the browser history.


Html keywords:

Structure:
;htmlKeyword keyword1,keyword2,keyword3,...

The ;htmlKeyword allows you to define the keywords which will be put in the header of the html files. This permits search engines like Google or Yahoo to reference easily your page.
The keywords should be separated by the "," character. Only the file which contains this tag will have these keywords specified. If you prefer specifying the keywords for all your files you document, use the Meta keywords for html option of the graphical interface (however, the ;htmlKeyword, if specified, would supersede this option).


Documentation generated by Cod2Doc on 09 Jul 2004.