What is Cod2Doc?

Introduction

What is Cod2Doc?

Cod2Doc is a documentation generator which parses Blitz Basic source files (Blitz 2D, Blitz Plus, Blitz 3D) and produces a set of documentation files in html describing variables, types and functions. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code. Cod2Doc uses comments in special locations to create the documentation. One goal of Cod2Doc is that you have to modify to a minimum the comments already in the code. Also, the advantage of Cod2Doc is that the code with the special comments are easy to read in the code itself (no odd tags that renders the code unreadable).

Using Cod2Doc has several advantages for developers:

it helps you to let your code documented in a clear way,
it creates a nice set of html files,
this html documentation is useful when you come back to the code after a few month pause,
this html documentation is useful when several persons work together on the same code.

But Cod2Doc is not only for developers, and here what it can do in addition:

document a library of functions/variables that you intend to make public,
create automatically .decls file to highlight your own functions,
create help files like this one made exclusively in Cod2Doc,
create a web page (like the Cod2Doc web page).

On top of that, Cod2Doc is user friendly as everything is done using a graphical interface easy to use. Cod2Doc is fully configurable and you can use it in lot of different ways. Here is a screenshot of the graphical interface:

Cod2Doc was written in Blitz3D by RepeatUntil (version 0 started in August 2003).
E-mail: repeatuntil@free.fr.
Web page: http://repeatuntil.free.fr/cod2doc.

To start quickly using Cod2Doc, please go on the example chapter.

Cod2Doc produces only html files. If you would like to convert your documentation into pdf files, then you could try htmlDoc.

Cod2Doc features

General features:

Document constant variables, global variables, arrays, types, functions (arguments, return value, examples), or choose to include only a subset of these.
Option to display the summary of all documented variables and functions at the top of the documentation.
Option to make the .bb source file accessible from the documentation.
Option to document functions in separate html files (similar to the Blitz command reference).
Option to highlight your own functions and access the quick help and your documentation by pressing F1 in the IDE (like any Blitz command!).
Group variables or functions linked to the same functionality together in the documentation.
Possibility to document one file, a whole directory, or directories and all its subdirectories.
Possibility to choose the directory where html files will be stored.
Simple to use thanks to the Graphical Interface (using Xlnt ii). This interface allows you to fully configure Cod2Doc.
Complete support for drag and drop (on the exe icon or directly on the application).
Special format of file (.c2d) to produce library, help files or web pages (see inline documentation below).
Come with a complete help file (produced with Cod2Doc!) and some examples to start quickly.

Special tags:

Author, Version, Last update, Project, See Also tags, and more...
Several way to include code (inline or from a file). And the code is highlighted like in your preferred IDE!
Tags to add title and meta keywords to the html.
Use any html code in your comment.

Automatic links and insertions:

Automatic recognition of function or variable links.
Crossed links.
Type example.html and it will turn to a link to this page.
Type myProg.bb and it will also turn to a link.
Type repeatuntil@free.fr and it will turn to a link.
Automatic insertion of images: type picture.jpg or img.gif in your comment, and a picture is automatically inserted!
Automatic bullet and numbered list generation. Type a list like this one, and it will be automatically transformed in a html list!

Layout of the document:

Three different layouts possible: same order as the source file, sorted by category or alphabetically sorted by category.
Possibility to display in the documentation to which category (function, global variable, ...) the keyword belongs.
Description part of functions and variables in first position or in last position (just like in Blitz Basic).
Documentation with frame / without frame.
Links at top or no links at top.
Include html header and footer in your documentation.
Possibility to use any language in the documentation (six languages already included).
Height already defined styles for html documentation: BlitzBasic, Cod2Doc, DarkPrince, Blitz3D, Blitzui, Doiron, Xpeabars, Tan. But you can create ANY style to fit with your web page for example!

Inline documentation:

Maybe the most powerful feature: possibility to add text anywhere in your program to increase or detail the documentation.
You can import a description of a variable or function from another file.
Lot of layout stuff to display title, section, paragraph, tables, ...
Special format of file to free the power of inline documentation: .c2d!
Create easily library documentation, help files (like this one) or even web pages with .c2d files!

What's new in the current version?

What's new in Cod2Doc version 1.2?

Drag and drop functionnality:
-> drag file(s)/directory(ies) on the Cod2Doc .exe icon, and Cod2Doc will start documenting the given files.
-> drag a file or a directory on the Cod2Doc application, and Cod2Doc will document it.
Cod2Doc can now be easily interfaced with any IDE (if the IDE developper want to implement it!). If you are an IDE developper and you wish to add an easy access to Cod2Doc from the IDE, please read this or contact me at repeatuntil@free.fr.
Cod2Doc can now be called with a command line.
Now you can add your own html header and footer to the documentation.
Re-organisation of the Cod2Doc interface.
New veto tag: put ;!! after a variable/type/field/function prevent it to be documented.
Formatting of html improved. No more text going beyond the table.
New styles added:
-> styles identical to the one of Blitz 3D: Blitz3D.
-> styles inspired from www.blitzbasic.com: Blitzui, Doiron, Tan, XpeaBars.
New languages added: japanese, german, italiano, portuguese, spanish (many thanks to BitManiak, Kbit, Luiz Ribeiro, René Aye).
Added a "Save" button for the configuration file ("Application" tab) to save the options of Cod2Doc.
Bug with type in function argument for decls file corrected.
A few more bugs were also corrected...

Thanks to BitManiak, Noel Cower, Pudding for the useful suggestions!

What's new in Cod2Doc version 1.1?

Option to make the .bb source file accessible from the documentation.
Possibility now to add images to style files (.css): see this in action with the DarkPrince style, done by Nebula.
And the NICEST NEW FEATURE: option to highlight your own functions and access the quick help and your documentation by pressing F1 in the IDE (like any Blitz command!). Now you have no limit to document libraries!
All known bugs of v1.0 corrected.

What's new in Cod2Doc version 1.0?
Everything, by definition !! ;-)

File organization: where is stored the documentation?

First of all, the graphical interface allows you to choose the directory where the documentation will be stored. By default, it's the Cod2Doc folder created in the directory containing the source files. All the documentation is located in this directory. The name of the html file is simply the name of the source file followed by the .html suffix. If the separate function option is set, then the name of the html file is the name of the function with the .html suffix.

There is also an index file created by Cod2Doc: this index file contains links to files which were created during the treatment. Warning: this file is erased each time you recreate documentation in this directory! The name of this file is index.html or indexFunctions.html when the separate function option is set. Note that for .c2d files, no index file is created.

In the directory containing the documentation, Cod2Doc creates also the files\ directory containing all the secondary files necessary to the documentation. You can use too this directory to store images or source files which are linked in your documentation.

Some technical notes:
The main html file is located in the output directory and has the name filename.html (where filename is the source file name). If the documentation has frames, two secondary files are stored in the files\ directory: filename_main.html which contains all the text of the documentation, and filename_links.html which contains the mini-index (which is the small frame containing links at the top of the documentation).

Moreover, in the frame mode, the frame containing the documentation text is called main under html and the mini-index frame is called links.