Question

我有一个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结构。

如果有帮助，我愿意改变我的评论格式。

Answer 1

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

您可以使用Template.getRootTreeNode()来检索模板的顶级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

你如何解析评论由你决定; - ）

更新：在我的备份和uploaded it to GitHub中找到了名为ftldoc的内容。也许这就是你要找的......

为FreeMarker FTL库生成HTML文档

1 个答案: