为 FreeMarker FTL 库生成 HTML 文档

Question

我有一个 FreeMarker 库，我想随我的产品一起发布，我正在寻找一种方法来根据 FTL 文件中的 cmets（以 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 中没有编写 cmets 的标准方法（例如 Javadoc 中的 @param 或 @returns）。

我不介意为此推出自己的解决方案，但我热衷于使用现有系统，例如 Doxia（因为我使用 Maven 来构建项目）或 Doxygen，而不是从头开始编写一些东西。 理想情况下，我只想编写注释解析代码，并依靠其他东西来检测宏并生成文档结构。

如果有帮助，我愿意更改我的 cmets 的格式。

Answer 1

如果您决定编写自己的文档生成器或为现有文档生成器编写特定于 FTL 的前端，您可以重用 FreeMarker 的一些解析基础架构：

您可以使用Template.getRootTreeNode() 来检索模板的顶级AST 节点。因为宏和响应的 cmets 应该是这个顶级节点 (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

如何解析评论取决于你 ;-)

更新：在我的备份和 uploaded it to GitHub 中发现了一个名为 ftldoc 的东西。也许这就是你要找的……