« | Main | »

Additions to HTML documentation generator

By Jewe | January 18, 2015

I have added an @include directive to the HTML documentation generator.

This directive expects a full or partial file path as an argument. Variables in the format {variable} may be used to specify the root of the include directory.

When generating HTML documentation for a class’s tags, the generator will load the specified text file and insert it in place of the @include directive. The text file is supposed to contain plain text or HTML text (without the head / body sections).

This makes it much easier to write comprehensive documentation for a class and it’s methods, since you can edit (and preview) your HTML in an external file and have the HTML documentation generator include that file later.

Here’s an example of including documentation in a native class declaration:

native class UrlGenerator
    ["A class that allows dynamic creation of URLs from a generator expression.
        <div>@include {textinclude}urlgenerator.html</div>"]
    method UrlGenerator(const string expression);
    method string[] Execute(const string template);
    accessor int Valid();

The C++ binding code generator will not perform the text-include, it will just use the tag’s content as-is. So your binding code will look like this:

static const char* kClassDeclaration =
    TAG("A class that allows dynamic creation of URLs from a generator expression.
        <div>@include {textinclude}urlgenerator.html</div>")
    "method UrlGenerator (const string expression);" TAG("")
    "method string[] Execute (const string template);" TAG("")
    "accessor int Valid ();" TAG("")

To take advantage of the {textinclude} variable expansion, you must make sure to define the variable when you run the HTML code generator. The best way to do this is by specifying the variable definition as a parameter to JCLGenerateDocs().

This is an example script of JILRun creating documentation for itself:

import all;

function string main(const string[] args)
    // generate docs but ignore the built-in runtime class
    return "";

The native C / C++ code for calling JCLGenerateDocs() would look very similar. The parameters are exactly the same.

As you can see, I have used forward slashes for the path, so I don’t get problems with ANSI escape characters. The @include directive will transform these into backslashes on Windows-based systems.

The variable {textinclude} is just an arbitrary name I have chosen; you may choose any number of your own variable names. This may be beneficial, if you have multiple roots of documentation sources. You may also use individual variables for every include file, if you’re so inclined.

Topics: docs, news | Comments Off on Additions to HTML documentation generator

Comments are closed.