What is jalapi

jalapi is the jallib API documentation. You access jalapi from here:

• jalapi

jalapi is directly integrated to jallib's SVN repository. You can also have access to jalapi while downloading a jallib package.

jalapi for developers

Description

jalapi documentation is generated from the comments found on jal libraries, particularly from:

• JSG headers. A library must be strictly JSG compliant before being integrated to jalapi.

• comments found directly above var, const, procedure and function.

How to write comments

The two following examples show how to comment correctly your code so jalapi can extract them.

good

-- this my procedure
-- it's amazing !
procedure my_proc() is
end procedure

bad

-- this is still my procedure

-- it's not that amazing
procedure my_proc() is
end procedure

On the second example, only the very first line above the procedure will considered as doc, because there's an empty line. That is, jalapi the whole comment block above, until it finds an empty line.

About syntax...

jalapi is also converting your comments in html, following the Google Code Wiki Markup Syntax. That is, you can add bullet list, tables, etc... just you'd do here, in a wiki page. But, while GC wiki doesn't respect line feeds (or carriage return), jalapi tries to keep your carriage return: when there's a "\n", it produces an "<br/>" html element.

Finally, keep in mind the following rules: don't make too fancy comments. While this sounds beautiful in your code (though it can be heavy to read), it'll be converted to html, and this can sometime produces weird things.

Exception: long dash lines, used to ease the identification of code block, can be used in a jal file, but will be removed while generating html. To be precise, everything starting with "-- -" will be ignored. Ex:

-- --------------------
-- this is my comment
-- --------------------
procedure blabla() is
   --
end procedure

will only keep "this is my comment".

Keep it simple !

Howto generate doc

There are two main scripts to generate your documentation. Both can only be run from Linux, because they uses grep, sed...

jalapi.py

jalapi.py takes a template and a jal file as inputs. It also needs SAMPLEDIR environment variable to be defined. It prints the html result on stdout.

Ex

cd path/to/tools
SAMPLEDIR=../sample python jalapi.py jalapi_html.tmpl mylib.jal > mylib.html

Since html files are directly integrated to SVN, and served by GC apache server, you need to adjust the mimetype of generated files, so there're "real" html files, and not just raw ascii text (it won't display correctly if you don't do this):

svn propset svn:mime-type text/html mylib.html

jalapi_generate.sh

Because all of this can be a real p.i.t.a, there's another script gluing the whole, which automatically generate documentation for all libraries found, except device files. (device files are not considered because there's no such comments in code, this generates a lot of duplicate information)

Running this script is simple as:

cd ..../tools
./jalapi_generate.sh path/to/trunk

It automatically find libraries, sets SAMPLEDIR, add files to the doc/html directory and correctly set SVN properties.