Создание HTML-документации для библиотеки FreeMarker FTL - PullRequest
Новая
       2

Создание HTML-документации для библиотеки FreeMarker FTL

1 голос
/ 10 июня 2011

У меня есть библиотека 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, вместо того чтобы писать что-то с нуля. В идеале я хотел бы написать только код для анализа комментариев и полагаться на что-то еще для определения макросов и создания структуры документа.

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

1 Ответ

2 голосов
/ 10 июня 2011

Если вы решите написать собственный генератор документов или написать специфичный для 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

То, как вы анализируете комментарий, зависит от вас; -)

Обновление : обнаружил что-то с именем ftldoc в моих резервных копиях и загрузил его на GitHub . Может быть, это то, что вы ищете ...

...