Skip to content

Generate Html Api Documentation

coldwell edited this page Mar 21, 2012 · 3 revisions

When ColdDoc was first conceived, it's sole purpose was to general static HTML documentation based on Javadoc for CFCs. In this version things have changed a little.

ColdDoc now has a series of Documentation Template Strategies that can be used to generate a variety of documentation, including, but not limited to the original HTML Javadoc port.

This means that when using ColdDoc, you have to also instantiate the appropriate strategy that you want to use. This could be a strategy that comes bundled with ColdDoc, or possibly a strategy of your own.

To generate documentation, first we instantiate Colddoc:

colddoc = createObject("component", "ColdDoc").init();

Next, we create some sort of Strategy for it to use, and set it as the strategy that ColdDoc will use to generate documentation:

strategy = createObject("component", "colddoc.strategy.api.HTMLAPIStrategy").init(expandPath("./docs"), "ColdDoc 1.0 Alpha");
colddoc.setStrategy(strategy);

From here, there are 2 ways in which we can invoke the generate() method on Colddoc:

If we only have a single directory with a single mapping, it can be done easily like so:

colddoc.generate(expandPath("/colddoc"), "colddoc");

Which passes into ColdDoc the absolute path to the mapping, and also the name of the mapping, and tells it to generate the documentation based on the CFCs it finds there.

If you have multiple mappings/directories that you want to be able to document with ColdDoc, you can simply pass an array of structs containing inputDir and inputMapping keys into ColdDoc's generate() method.

For example:

paths = [
          { inputDir = expandPath("/colddoc"),inputMapping = "colddoc"}
          ,{inputDir = expandPath("com")
           ,inputMapping = "com" }
];
colddoc.generate(paths);

The reason we use an array of structs is because it is possible to have the same mapping in a system point to two different locations. I.e. there could be a server mapping that points to a directory, and a local directory with the same name, and they overlap. This gives the ability to be able to handle those situations.

HTML API Strategy

To create the static HTML documentation that ColdDoc originally started with, use the strategy colddoc.strategy.api.HTMLAPIStrategy, whose init() method takes the path to generate the HTML files in, and the title that you wish to use for your documentation.

Click here to see an example of HTML API output.

For example:

colddoc = createObject("component", "ColdDoc").init();
strategy = createObject("component", "colddoc.strategy.api.HTMLAPIStrategy").init(expandPath("./docs"), "ColdDoc 1.0 Alpha");
colddoc.setStrategy(strategy);
colddoc.generate(expandPath("/colddoc"), "colddoc");

This will generate the HTML documentation in expandPath("./docs") with the title "ColdDoc 1.0 Alpha".