« | Main | »

HTML documentation engine

By Jewe | October 29, 2012

This is a short introduction to the HTML documentation engine, which was introduced with the JewelScript update.

If you are an experienced Java or C++ developer, you may have become very fond of documentation generation tools like Javadoc or Doxygen. These tools analyze source code comments and derive documentation from them, usually generating a set of HTML files. In these HTML files, developers can browse existing classes and methods in order to get a clean, structured overview.

Having useful documentation never hurts – but it is even more crucial for the native bindings you create for your application. If you can’t tell script programmers what tools are there for them to use, the whole idea of adding scripting support is moot. However, due to the way native classes are designed and bound to the runtime, there is no way to use existing source code documentation tools.

At one point, I had too many different applications embedding too many native bindings to remember anything about them, so I was becoming quite frustrated about the lack of documentation. So I added a HTML documentation generator to the library.

JewelScript tags

To make adding source code documentation as simple as possible, I added the possibility to add a tag to a function, method, class or delegate declaration. The main purpose of the tag, for now, is to add documentation to the language construct. There may be other uses in the future as well. Here is a code example:

native class Hello
    ["This is a documentation tag for class Hello."]
    method Hello();         ["This is a documentation tag for the constructor"]
    function int Test(int); ["This is a documentation tag for function Test()."]

Tags are not limited to native type declarations – you may very well use them to document script classes, too. But it’s the native classes where they are particularly important.

When compiling tags, the compiler just memorizes their contents for later use by the HTML documentation engine.

Tags in native C++ code

The easiest way to add tags to your native type is by already adding the tags to the native class declaration, as shown above. The C++ binding code generator will then take care of properly adding your documentation to the binding code file. However, sometimes you may wish to add the documentation at a later stage, which is not a big deal either.

Consider this example declaration:

static const char* kClassDeclaration =
    TAG("TODO: You can fill these tags with documentation.")
    "method Point ();" TAG("")
    "method Point (int x, int y);" TAG("")
    "accessor int X ();" TAG("")
    "accessor int Y ();" TAG("")

This declares a native “Point” class, which represents a two dimensional coordinate on the screen. Notice the TAG() macro after each declaration. This will append the documentation tag for the language construct in debug builds. Meaning, you can use the debug build of your application to generate HTML documentation, but the tags will be stripped from the release build of your application, making it more compact.

Tag inheritance

If your class implements an interface, extends a class or inherits from multiple classes, all tags of the base classes will be inherited as well. This allows you to only focus on documenting new functions and leave documentation of inherited functions up to the base class.

Of course you may also “override” inherited documentation tags in the new class, if you wish to do so.

The compiler will inherit a tag, if the base class method has one, but the sub class either doesn’t override the method, or does not specify a new tag for the overridden method.

HTML code in tags

To improve formatting of the generated documentation, you may use HTML tags in the documentation. However, be sure to use XHTML conformant tags. For every tag, you must specify the correct closing tag, even for tags like “p”, “li” or “br”, which do not require a closing tag in transitional HTML.

You also need to correctly encode special characters, for example the apostroph ' quotation mark " greater than > or smaller than < characters.

Finally, remember that JewelScript strings are 8-bit only, so you may have to use HTML entities to express other unicode characters.

Invoking the HTML documentation engine

The engine can be invoked anytime after successfully compiling script code by calling the JCLGenerateDocs() API function.

It will run through all types currently known to the compiler and create documentation for them, but only if they contain at least one tag. To make sure all of your application’s native types get documented, you have to import them. As of JewelScript, you can use the import all statement to automatically import all native types your application has registered with the runtime.

This is an example of the output generated by the HTML documentation generator: JILRun Class Documentation.

Excluding classes from documentation generation

Under certain circumstances it can become necessary to exclude a class from the documentation generation process. To do this, simply use the token @ignore in the tag of the class you wish to ignore.

You may also do this from outside of the class, by passing the expression @ignore=ClassName in the parameter string of the JCLGenerateDocs() function.

Extra parameters for the documentation generator

The parameter string of the JCLGenerateDocs() function allows to define user variables. The most important variable to set is the application variable. This will define the application name / title for the generated output:

err = JCLGenerateDocs(
    "application=JILRunOnly, verLibQL=1.4, @ignore=runtime"

You may define your own variables and have them inserted into the documentation, by using the variable name in curly braces in the documentation tag:

function Foo(); ["Requires version {verLibQL} of the QL-library."]

XML type export

In addition, the compiler can export all known types to an XML file. This gives people the opportunity to come up with a more advanced documentation generation tool. It could also be used in a source code editor or IDE to get a complete XML model of the program currently being developed.

To do this, simply call the API function JCLExportTypeInfo() after successfully compiling or importing classes.

Here is an example of the XML type export, generated only from the built-in classes: types.xml.

I’d like to emphasize that both the HTML documentation generator and the XML exporter are completely ANSI C compliant, and require no external tools or libraries. They are handcrafted using only the string functions of the JewelScript compiler.

Topics: docs | Comments Off on HTML documentation engine

Comments are closed.