Model a reference documentation and render-engine for a runtime spring-context

Question

I am about to generate a reference documentation for a big bunch of spring-beans that are configured and assembled at runtime. The basis for the documentation is javadoc.

In the first step I collect a map of classname <-> raw-class-documentation using a simple doclet.

Then I launch the spring container and find all those beans that I am interested in.

Now I want to render the documents, but I need guidance with toolset and data-modeling.

1) The actual datamodel does not reflect what I want to document, e.g. Components have a list of rules, but I want to show in which components the rules are used. How should I model that? Sounds roughly like "DisplayData" objects ....

2) What is the most clever way for rendering? I thought about xml + xsl-stylesheet, or perhaps some template engine?

3) perhaps there is already a framework to produce reference documentation that supports most of the stuff ?

Answer 1

I've done something similar not long ago. I try to explain it briefly so you can decide if it fits your scenario:

We started to implement business rules in a fairly standardized way. The general idea here is to encapsulate an atomic rule in a single method with a common signature: myRule(fact, executionContext). Then these atomic rules are grouped, ordered and mapped onto arbitrary events in the system. This design allowed us to generate a documentation that shows what rules are executed on what events together with some business docs extracted from javadoc.

I've used QDox to traverse the classes, extract javadocs together with some technical information and build a model. For the actual doc generation I've used Freemarker templates. In my case the output was in html and mediawiki format.

When designing your model you have to keep in mind what the actual documentation should look like so that in your templates you can use the model in a simple, convenient way. Let's take a simple example: you want a main page with all the rules listed and then another page for each rule where you show some details (javadoc, signature, etc.) and all the components where it is used. In this case you should create a model like this:

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

class Component {
    ...
}

At the end you will have a list of Rule objects what you can pass to the templating engine.

Answer 2

For the sake of completeness I post my solution here:

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