为运行库spring上下文建模参考文档和呈现引擎

Question

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

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

然后我启动弹簧容器，找到所有我感兴趣的豆子。

现在我想呈现文档，但是我需要工具集和数据建模的指导。

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

2) --什么是最聪明的呈现方式?我想过的+xsl样式表，或者可能是一些模板引擎？

3) 可能已经有了一个框架来生成支持大部分内容的参考文档？

Answer 1

不久前我也做过类似的事。我试着简单地解释一下，这样您就可以决定它是否适合您的场景：

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

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

在设计模型时，您必须记住实际的文档应该是什么样子，以便在模板中您可以以简单、方便的方式使用模型。让我们以一个简单的例子为例:您需要一个包含所有规则的主页，然后为每个规则提供另一个页面，其中显示一些细节(javadoc、签名等)。以及使用它的所有组件。在这种情况下，您应该创建如下模型：

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

class Component {
    ...
}

最后，您将有一个规则对象列表，您可以传递给模板引擎。

Answer 2

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

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();
    } 
  }
}