为 FreeMarker FTL 库生成 HTML 文档

Posted 2023-02-19

【中文标题】为 FreeMarker FTL 库生成 HTML 文档

【英文标题】：Generate HTML documentation for a FreeMarker FTL library

【发布时间】：2011-09-12 03:01:54

【问题描述】：

我有一个 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 的格式。

【参考方案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 的东西。也许这就是你要找的……

【讨论】：

这一切听起来有些熟悉，好像我多年前做过类似的事情，所以我用谷歌搜索并搜索了我的备份，确实找到了我的一个旧项目，名为ftldoc，它为 FTL 生成 HTML 文档文件。我会把它上传到某个地方（也许是 GitHub？）并在这里发布一个链接 :-)

谢谢，这正是我想要的，我什至可以分叉它并添加新功能:)