CODEWITHSUNDEEP
documentation-generationfreemarker
Nico
Nico

Reputation: 811

Generate HTML documentation for a FreeMarker FTL library

I've a FreeMarker library that I want to ship with my product, and I'm looking for a way to generate a HTML documentation for it based on the comments in the FTL file (in a Javadoc fashion).

For example, a typical function in my library is written like:

<#--
  MyMacro: Does stuff with param1 and param2.
  - param1: The first param, mandatory.
  - param2: The second param, 42 if not specified.
-->
<#macro MyMacro param1 param2=42>
  ...
</#macro>

I didn't find anything on that subject, probably because there is no standard way of writing comments in FreeMarker (Such as @param or @returns in Javadoc).

I don't mind rolling my own solution for that, but I'm keen on using an existing system like Doxia (since I'm using Maven to build the project) or Doxygen maybe, instead of writing something from scratch. Ideally I'd like to write the comment parsing code only, and rely on something else to detect the macros and generate the doc structure.

I'm open to changing the format of my comments if that helps.

Upvotes: 1

Views: 1443

Answers (1)

Chaquotay inactive
Chaquotay inactive

Reputation: 2232

In case you decide to write your own doc generator or to write a FTL-specific front-end for an existing document generator, you can reuse some of FreeMarker's parsing infrastructure:

You can use Template.getRootTreeNode() in order to retrieve the template's top level AST node. Because macros and the responding comments should be direct children of the this top level node (IIRC), iterating over its children and casting them to the right AST node subclass should give you almost everything you need with respect to FTL syntax. To illustrate the approach I hacked together a little "demo" (cfg is a normal FreeMarker Configuration object):

Template t = cfg.getTemplate("foo.ftl");
TemplateElement te = t.getRootTreeNode();

Enumeration e = te.children();
while(e.hasMoreElements()) {
    Object child = e.nextElement();
    if(child instanceof Comment) {
        Comment comment = (Comment)child;
        System.out.println("COMMENT: " + comment.getText());
    } else if(child instanceof Macro) {
        Macro macro = (Macro)child;
        System.out.println("MACRO: " + macro.getName());
        for(String argumentName : macro.getArgumentNames()) {
            System.out.println("- PARAM: " + argumentName);
        }
    }
}

produces for your given example macro:

COMMENT: 
  MyMacro: Does stuff with param1 and param2.
  - param1: The first param, mandatory.
  - param2: The second param, 42 if not specified.

MACRO: MyMacro
- PARAM: param1
- PARAM: param2

How you parse the comment is then up to you ;-)

Update: Found something called ftldoc in my backups and uploaded it to GitHub. Maybe this is what you are looking for...

Upvotes: 2

Related Questions