Inline Documentation

Inline documentation

What is inline documentation?

Introduction:

Inline documentation is a very useful kind of comment that you should use often. For example, these help html files as well as the Cod2Doc web page were all created thanks to inline documentation!
It allows you to put documentation outside of variable and function description. This permits to have text between variables and functions.
There is also a special format of files treated by Cod2Doc: the .c2d files. These files contains only inline documentation and are very useful to document libraries, to create help files or web pages. The .c2d files are treated in this section.

How to use it:

Structure:
;doc
; Some documentation here
;/doc

You may start an inline documentation anywhere in the Blitz Basic file (except in a variable/function description). The inline documentation is started with the ;doc tag, and ended with the ;/doc tag. Any comments in-between these two tags are considered as inline documentation. There should be only comments in inline documentation.

There is three possible locations of an inline documentation in the Blitz Basic file:

In the header.
The header is defined as the part of the file between the first line and the first non commented line. An inline documentation in this part will placed in the header of the documentation. Sometimes it may be useful to define yourself the end of the header: see the tag ;endHeader.
Before a variable, type, function.
The inline documentation will be always placed before this keyword, independently of the definition of the layout.
In the footer.
If the inline documentation is placed after the last non commented line, then it will appear at the end of the html file.

The comments entered in the inline documentation may be of two types:

Simple comments, which will be printed as text in the html documentation. See the next section for more details.
Cod2Doc tags: all the tags described in the tag chapter are available, plus special tags that are defined below.

Of course, automatic links and insertions work still in the inline documentation.

Example:

Example:
;doc
;title An inline documentation example
; Here is some text in the inline documentation

;table Here is a table
;cell a cell
; Some text in the cell
;/cell
;/table

; Finally some text here
;/doc

; This is the description of the function
Function FunctionExampleDoc()
End Function

This gives this result:

An inline documentation example

Here is some text in the inline documentation

Here is a table

a cell
Some text in the cell

Finally some text here

FunctionExampleDoc()

Description:
This is the description of the function

Return value:
None

Normal text in inline documentation

Text in inline documentation has a formatting very similar as normal comments in your code. The only difference is that it's possible to add empty line between comments. Adding an empty line has the effect that next comment will begin on a new line. You can insert as many empty lines as you wish, no effect will be seen on the documentation format.

Here is an example:

Example:

Example:
; This text and
; this text are on different lines,
;; but this one continue previous line thanks to ";;"

; The blank line above starts a new line.
;
; The blank comment adds a blank line between the two paragraphs.

This gives this result:

This text and
this text are on different lines, but this one continue previous line thanks to ";;"
The blank line above starts a new line.

The blank comment adds a blank line between the two paragraphs.

Special tags for inline documentation

Index of tags only for inline documentation:

In addition to normal text, there is a lot of tags that may be placed in the inline documentation. All the tags described in the tag chapter are available.
Furthermore, there are special tags available only in inline documentation:

;anchor
;cell
;/cell
;chapter
;includeDescription
;includeDescriptionNoDoc
;line
;paragraph
;section
;table
;/table
;title

Layout tags:

Adding title, chapter, ...:

Structure:
;title A title
;chapter A chapter
;section A section
;paragraph A paragraph

Result:

A title

A chapter

A section

A paragraph

Line:

Structure:
;line

This tag is used to add a horizontal line in the inline documentation like this one:

Table tags:

Structure:
;table Title of the table
;cell Title of the first cell
; Text inside the first cell
; Some more text
;/cell
;cell Title of the second cell
; Text inside the second cell
;/cell
;/table

;cell Title of the first cell
; Text inside the first cell
;/cell
;cell
; Text inside the second cell
;/cell

Two kinds of tables are possible inside inline documentation:

table with a cell containing a title
table containing only normal cells

See the result below to see how the tables look like.

The ;cell tag may be without text, which has the effect to create a cell without title. The ;/cell tag is optional (except the last one!): it's automatically added where it needs to be. The ;cell and ;table tags may be extended by the ;+ tag to have longer text title.
If the ;/cell and ;cell keywords are following each other, they will belong to the same table (otherwise a new table is created).

Result:

Title of the table

Title of the first cell
Text inside the first cell
Some more text

Title of the second cell
Text inside the second cell

Title of the first cell
Text inside the first cell

Text inside the second cell

Html reference:

Structure:
;anchor theAnchorName
; To make a link from the same file to this anchor:
; [text of the link]theAnchorName.
; To make a link from another file to this anchor:
; [text of the link]fileName.html#theAnchorName.

This tag allows you to place an anchor inside the html document. This anchor may be referenced later in the same document or within any documents.

To make a link to this anchor in the same file, you just have to type the name of the anchor preceded or followed by brackets ([]) containing the text of the link. The anchor won't be referenced if no brackets are specified.

To make a link to this anchor from another file, you have to use the automatic links: fileName.html#theAnchorName[text of the link] where fileName.html is the name of the file containing the anchor.

Warning: anchors are case sensitive!

Example:

Example:
;anchor exampleOfAnchor
; This text has an anchor
;
; Click [here]exampleOfAnchor to go to the anchor.
; Here is an example of an anchor outside this file: LinksAndInsertions.html#htmlLinks[see here].

This gives this result:

This text has an anchor

Click here to go to the anchor.
Here is an example of an anchor outside this file: see here.

Include a keyword description from another file:

Structure:
;includeDescription fileName.bb#keyword
;includeDescriptionNoDoc fileName.bb#keyword

This tag is one of the most powerful tag in Cod2Doc! The most common way to use it is inside .c2d files. It's very useful when you want to document a library for example. It allows you to add in the inline documentation a description of a given keyword (variable, type, function) from a given file. Cod2Doc scans the file looking for the given keyword: if it finds this keyword (for example a global variable or a function), then it just cuts and pasts the whole description of this keyword in the inline documentation.

The difference between the ;includeDescription and ;includeDescriptionNoDoc tags is the following: in the case of the ;includeDescription tag, if an inline documentation is found before the keyword, this inline documentation is also pasted with the description of the keyword. On the contrary, for the ;includeDescriptionNoDoc tag, the inline documentation related to the keyword won't be inserted.

Notice that a path may be added to the file name.

Example:

Example:
; An ;includeDescription which takes the inline documentation related to aFunction:
;includeDescription ExampleIncludeDescription.bb#aFunction
;
; An ;includeDescriptionNoDoc which doesn't take into account the inline
;; documentation related to this variable:
;includeDescriptionNoDoc ExampleIncludeDescription.bb#anotherVariable

The file ExampleIncludeDescription.bb:
Global aVariable ; Description of aVariable
;doc
; Some inline documentation related to the variable
;/doc
Global anotherVariable ; Description of this variable

;doc
; Some inline documentation related to this function
;/doc
; Description of this function
Function aFunction()
End Function

This gives this result:

An ;includeDescription which takes the inline documentation related to aFunction:

Some inline documentation related to this function

aFunction()

Description:
Description of this function

Return value:
None

An ;includeDescriptionNoDoc which doesn't take into account the inline documentation related to this variable:

anotherVariable

Description:
Description of this variable

Inline documentation files: .c2d files

The .c2d files are files containing exclusively inline documentation. The ;doc and ;/doc tags are optional. These files are very useful to produce for example:

help files like this one (entirely done with several .c2d files!)
documentation of library
web page (like the Cod2Doc web page entirely created with .c2d files!)
...

One of the advantage to use .c2d files is that it generates a html documentation which use cascading style sheets, a very practical way to change easily the style of the page without changing a line of the html page! See the chapter on styles to have more details on this.

Example:

Here is an example of a .c2d file:
;title Example of a .c2d file
; Some text here

;version 0.0
; And an example of the very useful ;includeDescription tag:
;includeDescription ExampleIncludeDescription.bb#anotherVariable
; End of the .c2d file

This gives the result, after a treatment by Cod2Doc:

Example of a .c2d file

Some text here

Version:
0.0

And an example of the very useful ;includeDescription tag:

Some inline documentation related to the variable

anotherVariable

Description:
Description of this variable

End of the .c2d file

You can study more complete examples: all the .c2d files used to create this documentation and the Cod2Doc web page are accessible for you! Just go in these directory:

The .c2d files doesn't appear in an index file like .bb files (as you will be the only person to know what to put in a possible index!).

Notice that if you set the option with frame (see here), a mini-index will be created for you (the mini-index is the small frame at the top of the html page containing some useful links, like in this documentation). On the contrary of a .bb file, this mini-index is empty (Cod2Doc can't guess for you what links you want to put!). There is only one mini-index for the whole directory. This mini-index file is located in the directory Cod2Doc\files\ (replace Cod2Doc\ by the output directory if you changed it) and is called mini-index.html. You may modify it with a text editor or a html editor to include some links. Cod2Doc will never erase this file if you modify it!