fmdoc

FreeMarker Documentation Generator

Riot's fmdoc tool is a utility to generate JavaDoc-like documentation for FreeMarker macro libraries.

Demo

For an real-life example view the fmdocs for Riot's built-in libraries.

Syntax

The fmdoc syntax is very similar to JavaDoc comments. A fmdoc comment block starts with <#--- (note the three dashes) and ends with -->. Comments may precede functions, macros and global assign statements (variables). If the template starts with a fmdoc comment in the first line, the comment is used to describe the whole library.

Each comment block is made up of two parts – a description followed by a block of tags. Currently the following tags are recongnized by fmdoc: @see, @since, @returns and @param. Additionally two FreeMarker specific tags are supported: @internal and @namespace.

<#---
  - Displays a colorful greeting.
  - @param person The name of the person to say hello to
  - @param color The font color
  -->
<#macro greet person color="black">
  <font color="${color}">Hello ${person}!</font>
</#macro>

You can use the @internal tag to exclude functions or macros from the documentation.

Note:

Currently fmdocs are only generated for templates that have a @namespace tag in their first comment block. This tag identifies a template as macro library and defines the name under which the template is listed in the library index.

Usage

To generate documentation for your libraries use the fmdoc Ant task. Note that fmdoc.jar and freemarker.jar must be included in the referenced classpath.

<target name="fmdoc">
  <taskdef name="fmdoc" classpathref="classpath"
      classname="org.riotfamily.fmdoc.ant.FreeMarkerDocTask" />
  <fmdoc destdir="fmdoc">
    <fileset dir="src">
      <include name="**/*.ftl" />       
    </fileset>
  </fmdoc>
</target>

Download

The fmdoc binaries can be downloaded here. If your project uses Ivy you can also retrieve fmdoc from our Ivy repository.

The source code is accessible via anonymous SVN at
http://svn.riotfamily.org/svn/fmdoc/trunk/

Changelogs are available via FishEye.

License

Fmdoc is available under the terms of the Mozilla Public License 1.1.

Feedback

If you have any questions please write a mail to the riotfamily mailing list. In case you found a bug or want to propose a new feature, please use our issue tracking system.