ColdDoc is one of those projects I don’t work without these days. No matter the project, I’ve always got a stack of CFCs in it, and I need a way to document what objects I have, and what methods they have on them. A great example being the
ColdSpring 2 project. I’ve got my local
Jenkins install hooked up to generate the ColdDoc documentation on each run, and I usually run it locally often while developing, so I have an up to date reference of what methods are available to me, without having to dig into actual CFC code.
ColdDoc has been ready for 1.0 release for quite a while, but has yet to be formally pushed out into the wild.
With a little push from behind from
@vanderwoud, I got my planned migration of ColdDoc to GitHub into gear, and all is now complete.
Now
ColdDoc is hosted on GitHub, which is great, because it really is the best place to allow for community contributions, as well as the documentation ported over into the
Wiki.
ColdDoc 1.0’s big new ticket item is interface support (although it doesn’t support multiple interface inheritance), as well as lots of little bug fixes.
So if you are ready to get your automated documentation on,
grab a copy of ColdDoc, run it against your current code base, and see what comes out!
And if you have any contributions you would like to make to ColdDoc (and I’m sure there are some out in the wild), please issue a pull request against the repository.
When
ColdDoc was first born, the original idea was to just output a port of
Javadoc. Looking into it further, I realised that the mechanics where there to generate
any sort of documentation, not just a static HTML version of the API.
To
that effect, ColdDoc has been refactored so that it is possible to
generate documentation based on an arbitrary Template Strategy.
ColdDoc now ships with both a strategy that generates the port of
JavaDoc and a strategy that generates UML via the
UML2 Tools plugin in Eclipse, and plans are in the works to generate a PDF document strategy as well.
I won't take you through implementation details (there is new
documentation for that), but you can still generate the static HTML API documentation based on JavaDoc, for which you can see an example
here, but now it is done through the
HTMLAPIStrategy.
This also includes support for new ColdDoc based annotations, in which,
for example, you can specify generic types for return/arguments types
like array, struct etc, so you can finally answer that question in your
documentation of "Yes, but what does that array
contain?".
When
working on the ColdSpring 2.0 rewrite (wow, that is long overdue for a
blog post), I also really needed a way to generate UML diagrams from
the code I was writing, as a basic attempt to be able to roundtrip from
UML->CFC and then back again. Also included within ColdDoc is a
strategy to generate the XML that the Eclipse UML2 Tools Plugin uses to
create UML diagrams from. You can see a screenshot of a Class Diagram
here that has been created with this combination of tools.
This
is very useful, as it becomes very useful for collaboration and
software design sessions, even when you have started with UML diagrams,
as software designs can shift during implementation phases, and
diagrams and documentation often fall by the wayside during these rapid
change cycles.
If you are interested in more, or possibly
developing your own documentation generation strategies, download a
copy of ColdDoc, read the new
documentation, and join the conversation on the
google group.
Happy automation of documentation!
Not a huge amount to report here, this release fixes a bug in which if there is no 'init' method on a CFC, ColdDoc ends up throwing an error.
You can download ColdDoc 0.2 from here .
ColdDoc 0.1 is finally ready as a release version.
ColdDoc is a port of JavaDoc for ColdFusion, and generates static .html files that display API information for a collection of CFCs.
ColdDoc was initially written to output the API documentation for Transfer, which can be seen here .
The benefits of outputting documentation to static html files, rather than doing it dynamically include:
- Less processing at run time
- Documentation can be linked to, without fear of page names and/or anchors changing
- The ability to generate API details such as Direct known subclasses and Method Overrides information which would be too expensive to determine at run time.
Currently ColdDoc only supports a single root path, and is missing some JavaDoc implementations, such as a Index page, and Interface documentation, and can only run on ColdFusion 8.
ColdDoc can be downloaded from here .
