java - 为运行时 spring-context 建模引用文档和渲染引擎

Question

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

在第一步中，我使用简单的 doclet 收集类名 <-> raw-class-documentation 的映射。

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

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

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

2) 最聪明的渲染方式是什么？ 我考虑过 xml + xsl-stylesheet，或者可能是一些模板引擎？

3) 也许已经有一个框架来生成支持大多数内容的引用文档？

Answer 1

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

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

我用过QDox要遍历类，请提取 javadoc 和一些技术信息并构建模型。对于实际的文档生成，我使用了 Freemarker模板。就我而言，输出采用 html 和 mediawiki 格式。

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

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

class Component {
    ...
}

最后，您将获得可以传递给模板引擎的规则对象列表。