Блог

У меня есть библиотека FreeMarker, которую я хочу поставлять с моим продуктом, и я ищу способ сгенерировать HTML-документацию для нее на основе комментариев в файле FTL (в стиле Javadoc).

Например, типичная функция в моей библиотеке написана как:

 <#--
  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 нет стандартного способа написания комментариев (такого как @param или @returns в Javadoc).

Я не возражаю против создания собственного решения для этого, но я заинтересован в использовании существующей системы, такой как Doxia (поскольку я использую Maven для сборки проекта) или, возможно, Doxygen, вместо того, чтобы писать что-то с нуля. В идеале я хотел бы написать только код для разбора комментариев и полагаться на что-то еще для обнаружения макросов и генерации структуры документа.

Я открыт для изменения формата моих комментариев, если это поможет.

В случае, если вы решите написать свой собственный генератор документов или интерфейс для FTL для существующего генератора документов, вы можете повторно использовать часть инфраструктуры синтаксического анализа FreeMarker:

Вы можете использовать Template.getRootTreeNode() для извлечения узла AST верхнего уровня шаблона. Поскольку макросы и отвечающие комментарии должны быть прямыми дочерними элементами этого узла верхнего уровня (IIRC), перебор его дочерних элементов и приведение их к нужному подклассу AST node должен дать вам почти все, что вам нужно в отношении синтаксиса 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
  

То, как вы будете анализировать комментарий, зависит от вас 😉

Обновление: Нашел что-то под названием ftldoc в моих резервных копиях и загрузил это на GitHub. Возможно, это то, что вы ищете…