生成FreeMarker FTL库的HTML文档

如何解决生成FreeMarker FTL库的HTML文档

| 我有一个想随产品一起提供的FreeMarker库，我正在寻找一种基于FTL文件中的注释（以Javadoc方式）为其生成HTML文档的方法。 例如，我库中的一个典型函数写为：

<#--
  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>

我没有找到关于该主题的任何内容，可能是因为FreeMarker中没有标准的注释编写方式（例如Javadoc中的

@param

或

@returns

）。 我不介意为此使用自己的解决方案，但是我热衷于使用现有的系统（例如Doxia（因为我正在使用Maven来构建项目）或Doxygen），而不是从头开始编写东西。 理想情况下，我只想编写注释解析代码，然后依靠其他方法检测宏并生成doc结构。 如果有帮助，我愿意更改评论的格式。     

解决方法

        如果您决定编写自己的文档生成器或为现有文档生成器编写特定于FTL的前端，则可以重用FreeMarker的某些解析基础结构： 您可以使用ѭ3来检索模板的顶级AST节点。因为宏和响应注释应该是此顶级节点（IIRC）的直接子代，所以对其子代进行迭代并将其强制转换为正确的AST节点子类应为您提供有关FTL语法的几乎所有所需内容。为了说明这种方法，我一起砍了一些“演示”（

cfg

是正常的FreeMarker

Configuration

对象）：

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);
        }
    }
}

为您的给定示例宏生成：

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

然后，您如何解析注释；-) 更新：在我的备份中找到了一个名为ѭ8的东西，并将其上传到GitHub。也许这就是您要寻找的...