1

我即将为一大堆在运行时配置和组装的 spring-beans 生成参考文档。文档的基础是 javadoc。

在第一步中，我使用一个简单的 doclet 收集类名 <-> 原始类文档的映射。

然后我启动 spring 容器并找到所有我感兴趣的 bean。

现在我想渲染文档，但我需要工具集和数据建模方面的指导。

1) 实际的数据模型并没有反映我想要记录的内容，例如组件有一个规则列表，但我想显示在哪些组件中使用了这些规则。我应该如何建模？听起来大致像“DisplayData”对象....

2）最聪明的渲染方式是什么？我想到了 xml + xsl-stylesheet，或者一些模板引擎？

3）也许已经有一个框架来生成支持大多数东西的参考文档？

4

2 回答 2

1

我不久前做过类似的事情。我尝试简要解释一下，以便您确定它是否适合您的场景：

我们开始以相当标准化的方式实施业务规则。这里的一般想法是将原子规则封装在具有公共签名的单个方法中：myRule(fact, executionContext). 然后这些原子规则被分组、排序并映射到系统中的任意事件上。这种设计使我们能够生成一个文档，该文档显示在哪些事件上执行了哪些规则以及从 javadoc 中提取的一些业务文档。

我使用QDox遍历类，提取 javadoc 和一些技术信息并构建模型。对于实际的文档生成，我使用了Freemarker模板。在我的例子中，输出是 html 和 mediawiki 格式。

在设计模型时，您必须牢记实际文档的外观，以便在模板中以简单、方便的方式使用模型。让我们举一个简单的例子：您想要一个列出所有规则的主页，然后每个规则的另一个页面显示一些详细信息（javadoc、签名等）以及使用它的所有组件。在这种情况下，您应该创建一个这样的模型：

class Rule {
    String javaDoc;
    ...
    List<Component> componentsUsing;
}

class Component {
    ...
}

最后，您将获得一个 Rule 对象列表，您可以将其传递给模板引擎。

于 2013-11-29T20:41:23.193 回答
0

为了完整起见，我在这里发布我的解决方案：

abstract class Renderable {
  String id; //used to create links and pages
  String javadoc; //contains actual commentText
  Renderer renderer; //output-specifc renderer
  abstract String renderLink();
  abstract String renderFull();
}


class Component extends Renderable {

  /** renders a link to this component */
  public String renderLink() {
    renderer.renderComponentLink(this);
  }

  /** renders the details of this component */
  public String renderLink() {
    renderer.renderComponentFull(this);
  }
}

class Rule extends Renderable {
  List<Component> usedBy;

  /** renders a link to this rule */
  public String renderLink() {
    renderer.renderRuleLink(this);
  }

  /** renders the details of this rule */
  public String renderLink() {
    renderer.renderRuleFull(this);
  }
}

class Model {
  Map<String,Component> components;
  Map<String,Rule> rules;

  ...
}


/** May be subclassed for specific types of output */
class Renderer {
  public String renderRuleLink(Rule r) {
    ...
  };

  public String renderRuleFull(Rule r) {
    ...
    for (Component c : r.getUsedBy() {
      //Components can render themselves in the same way.
      c.renderLink();
    }
  };

  public String renderComponentLink(Component c) {
    ...
  };

  public String renderComponentFull(Component c) {
    ...
  };

  public void generate(Model m) {
    for (Component c : m.getComponents()) {
       //add link to overview-pages using c.renderLink();
       //add page with full docs using c.renderFull();
    } 
    for (Rule r : m.getRules()) {
       //add link to overview-pages using r.renderLink();
       //add page with full docs using r.renderFull();
    } 
  }
}
于 2013-12-05T07:32:25.713 回答