Examples for a quick start


A copy of the examples files may be found in the subdirectory Examples\ where was installed Cod2Doc. Run Cod2Doc on these example files, and experience yourself the many possibilities offered by this tool. You can switch for example between the different layouts, between the different styles or the different languages. You can choose different options like frame/no frame, with/without mini-index, ... Try also to run with the mode "separate functions" to see what happen...

The examples:

The castle example

This example shows you how to simply comment a file. Some variables/functions were commented, some not, just to show you that Cod2Doc behaves fine in every cases.

You can access to the commented code (sorry, Mark ;). To show you differences between options, here are the resulting html pages with several settings:

Tutorial 1: a simple example

This example gives you the basis to start with Cod2Doc.

Compare between the code and the documentation produced with Cod2Doc. Access to the documentation: resulting html page. This example uses the BlitzBasic style.

Code:
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!    Document the header     !!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
; This is the line of description of the file which will appear in the index.
; Of course you can add more line of description of the file.
; These lines will appear at the top of the documentation.
; Here this comment and
;; this comment are on the same line in the documentation (thanks to ";;"!)
;
; THIS HTML DOCUMENTATION WAS CREATED USING [THIS .BB SOURCE FILE]SourceSimpleExample.html.

;author  RepeatUntil (email address: repeatuntil@free.fr)
;project  Describe your project here.
;version  Write the version here
;creation  Write the date of creation here
;lastUpdate  Write the date of last update here
;bug  Write your bug here.
;toDo  Write your to-do list here

; These comments won't be taken into account
; as they belongs to nobody ;)


;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!    Document variables/types/functions     !!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Include "ComplexExample.bb"

; This comment is not taken into account
Const aConstVariable = 0 ; This comment is taken in the documentation
; This comment is not taken into account

Const anotherConstVariable = 5 ; Here is the description of this variable
;+ with several lines when you use the ;+ tag
;;+ and an attached line here thanks to ";;+".

Global aGlobalVariable ; The description of the variable
Global anotherGlobalVariable = 1 ;! This description is not documented as it starts with ;!


; Here you put the description of the type
; with as many lines as you want
Type aType
  Field field1 ; Description of this field
  Field field2 ; Description of the second field
               ;+ with several lines of description with the ;+ tag
               ;;+ and an attached lines with the ;;+ tag
End Type


; Put here the description of the function
; The description of argument is done like this:
; var1 = here is the description of this variable
; var2 = here is the description
;+       with the possibility to add more lines with the ;+ tag
;;+      and with an attached line here with the ;;+ tag
; var3 = another description
; return = the description of the return value
Function aFunction(var1%, var2$, var3# = 1.)
  Return True
End Function


;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!    Automatic liks and insertions      !!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

; Just to show that Cod2Doc is able to insert a lot of things everywhere
;; (as long as they are comments which will be documented)
; These examples are shown inside the description of the function, but in fact
;; they will work in the header, for variables, types, ...
;
; Just type the name of the variable/type/function to reference it:
; ex: anotherConstVariable%, aFunction() or aType~
; You can also put a text instead of the link
; ex: You can click anotherGlobalVariable[here] or [here]anotherGlobalVariable
; You can reference a variable which is an other .bb file (crossed link)
; (even if they are not in the same directory as long as Cod2Doc treated them at the same time):
; ex: MoreComplexExample#aFunction
; Html pages (on the web or local) or bb files:
; ex: http://repeatuntil.free.fr/cod2doc, [a more complex example]MoreComplexExample.html or files/SimpleExample.bb
; Mail address:
; repeatuntil@free.fr or even [my email address]repeatuntil@free.fr
; Image insertion:
; files/Cod2Doc.jpg or with a resize: files/Cod2Doc.jpg[60,20]
; In all the above example, you can request that there is no automatic links/insertions by
;; adding a ! in front of the name (you have also global options available in the main window):
; ex: !http://repeatuntil.free.fr, !Cod2Doc.jpg
; Normal list:
; - point 1
; Still point 1,
;; still point 1 on the same line
; - point 2    ;/list
; Numbered list:
; * point 1
; Still point 1
; * point 2    ;/list  
Function aFunction2()
End Function


;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!    Groups     !!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

;group This is a group
Global myFirstVariable
Global mySecondVariable
;/group


;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!    Including code     !!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

; There is several ways to import code. Here are two methods (see the .bb file)
;example
; ; This is an example
; For i = 1 to 10
;   Print "This is an example"
; Next
;/example
;!
;importExample files/ExampleImportedCode.bb
Function aFunction3()
End Function


Tutorial 2: a more complex example

This example will demonstrate some additionnal abilities of Cod2Doc. In particular, you will discover the usefulness of inline documentation.

Compare between the code and the documentation produced with Cod2Doc. Access to the documentation: resulting html page. This example uses the BlitzBasic style.

Code:
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!    Document the header     !!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
; This is the line of description of the file which will appear in the index.
; You can add more line of description of the file.
;! This line won't be document as it starts with the veto tag ;!
; These lines will appear at the top of the documentation.
;
; THIS HTML DOCUMENTATION WAS CREATED USING [THIS .BB SOURCE FILE]SourceMoreComplexExample.html.

;author  [RepeatUntil]repeatuntil@free.fr
;toDo  - Like for other tags,
;+     - you can easily create a list
;+     - with several points.     ;/list

;doc
; Here is an inline documentation
;; where you can put a lot of text.
; This inline documentation is related to the header.
; A lot of special tags are available for inline documentation
;; (see the last inline documentation in this file for details).
;/doc

;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!    Document variables/types/functions     !!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Include "SimpleExample.bb" ; There is no comment in documentation for include files


; The description of type/function could be above or below the keyword
;; (however the priority is for description above the keyword)
;see aType4~ (use of the "See also" tag)
Type aType3
  Field field1 ; Description of this field
End Type

;doc
; This inline documentation will be relative to the Type aType4~ as it precedes
;; it. Whatever how the layout is set, this inline documentation
;; will be always related to aType4~.
;/doc

Type aType4
; For those who prefers, you may write the description below
;; the Type keyword
  Field field3 ; Description of this field
End Type


; The description of type/function could be above or below the keyword
;; (however the priority is for description above the keyword)
; return = the description of the return value
Function aFunction(var1%, var2$, var3# = 1.)
  Return True
End Function

;doc
; This inline documentation is related to the function aFunction2() as it
;; precedes it.
;/doc

Function aFunction2(var1%, var2$, var3# = 1.)
; For those who prefers, you may write the description below
;; the function keyword
; return = There is no return in this function, so that this comment won't appear
End Function

; If you don't want to document a piece of code, simply add these 2 tags:
;noDocumentation
Const constVar1 = 0
Const constVar2 = 0
;/noDocumentation


;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!    Groups     !!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

; Behaviour of group depends on the layout you set in the main window:
; - You can group different type of variables/functions if the layout
;   is set to "Same order as the file"
; - If the layout is set to "Sorted by category", you can't mix variables with function, or
;   constant with global, etc...
; - The groups won't work when the layout is set to "Alphabetically sorted by category"
; See these examples and play with layout...

;group This is a group
;+ with several lines of description,
;;+ this one being on the same line
Global aVariable1
;doc
; Of course, you can put inline documentation inside groups!
;/doc
Global aVariable2
;/group

; A group without title
;group
Global aVariable3
Global aVariable4
;/group


;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!    Including code     !!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


; There is several ways to import code. Here are some other methods compared to !SimpleExample.bb
; The first example show that if you put ";example -", then the example file is not saved
; The second shows that if you use ;code, then you are able to change the title of the example
; The third example shows that you can ask for another name of file (default is the name of the function)
;example -
; ; This is an example
; For i = 1 to 10
;   Print "This is an example"
; Next
;/example
;!
;code[This is an example with an user defined title:]
; ; This is an example
; For i = 1 to 10
;   Print "This is an example"
; Next
;/code
;!
;code aVerySmallExample.bb
; ; This is an example with a change in the name of the file (see link)
; For i = 1 to 10
;   Print "This is an example"
; Next
;/code
Function aFunction5()
End Function



;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!    Inline documentation     !!!!!!!!!!!!!!!!!!!!!!!
;!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


;doc
;line
;
; This inline documentation is related to the footer (as there is no more
;; keywords below it). This inline documentation will demonstrate the
;; main possibilities of this very useful feature.

; If you use the ";;" tag instead of the ";" tag, different lines
;; like this one
;; and this one
;; will be displayed
;; on the same line in the browser
;; (better like this, no ? ;).

; To display text on different lines, use the ";" tag.
; Like this
; and this.

; Another possibility to display text on different lines, just insert a blank line between them.

; Like this

; and this.

; You can also add a blank comment ";" and a blank line will be also added.
; Like this
;
; and this.
;
; You have a lot of layout tags:
;title A title tag (;title)
;chapter A chapter tag (;chapter)
;section A section tag (;section)
;paragraph A paragraph tag (;paragraph)
;
; You can also easily add tables.

; First a table without title cell:

;cell The title of the cell
; The text inside the cell
;cell Another cell
;+ with more text
; The text inside the cell
; and still more text
;/cell

; A table with a title:

;table This is the table title
;cell The first cell
; Some text
;cell
; A cell without title
;/table

; You can also put some anchors anywhere in the inline documentation (notice that
;; variables/types/functions produce automatically anchors).
;anchor aTest
; For example an anchor was placed on this line.
;
;
; To reference it, simply write the name of the anchor with some text into brackets [like this]aTest.
; You can also of course have a link to a variable/function of this
;; file: aFunction(). Or even in another file: SimpleExample#aGlobalVariable.
;
; Another powerful feature: include a description of a variable/type/function from
;; a .bb file (here the type !aType from the file SimpleExample):

;includeDescription SimpleExample#aType
;
; On top of this, all the other tags and automatic links/insertions are also available here.
; Here are a few examples:
;
; files/Cod2Doc.jpg

;code[Some code]
; ; Here is some code
; CreateAQuake-LikeGame(5, "And prepare me some coffee, please") ;)
;/code
;group A group
; some text or whatever inside this group
; * even a list
; * with 2 points   ;/list
;/group

;/doc


Tutorial 3: a simple example of .c2d file

This example shows how to use .c2d files, which are files containing only inline documentation. It is specially suited for documenting libraries, creating help files like this one or even web pages.

Compare between the code and the documentation produced with Cod2Doc. Access to the documentation: resulting html page. This example uses the Cod2Doc style.

Code:
; The .c2d files are files containing only inline documentation.
; Refer to the example file MoreComplexExample.html to see more details on what
;; you can insert in inline documentation.

; The help files of Cod2Doc have been created using exclusively .c2d files! The
;; web page was also created with Cod2Doc!!

; But here I would like to demonstrate that .c2d files are perfect to document a library where
;; you want to document functions and variables in an order that is not the one from the .bb
;; program.

; For that, you have still to comment your functions/variables in the .bb code (which helps you
;; to maintain a clean code!).

; So let's start for a very basic example, using the functions/variables defined in the SimpleExample.bb
;; file.

;title A very useful library

; This is some text which will be placed before the description of my first variable (here
;; a type).

;includeDescription SimpleExample#aType
;
; Here some text again with a list:
; - point 1
; - point 2

; And now let's include the function aFunction:

;includeDescription SimpleExample#aFunction
;
; That's it for this example, hoping it will give you a lot of good ideas!!



Documentation generated by Cod2Doc on 09 Jul 2004.