I am going to say it; CFML is a beautiful language, but the documentation sucks big time.
When you look at the documentation we've enjoyed since day one from Java, we are truly spoilt. JavaDoc's while visually may not be winning any awards, it is must-have resource for any would-be and hard-core Java developer. Listing all the methods and classes available from the given libraries it gives us a real time view of what we are using.
The key to the success of JavaDoc is how it is produced. The classes, methods, and signatures are not hand crafted by developers. Because lets face it, we are generally pretty poor at documenting at the best of times. Instead JavaDoc inspects the actual class files and produces the documentation from there. There is no forgetting a method, or class. If its in the classpath, then it will be documented. Naturally the developer can add to this documentation using inline annotations.
For too long, the CFML world has suffered at the hands of 3rd party documentation efforts. This I believe has caused it to fall behind other languages and the ease at which some people can start plundering the CFML chests of all its goodies. Afterall, the only way to call a function is to know about it. The only way to know about a function is to hope it has been documented.
We've been involved with a number of projects where we have had PHP/ASP developers come over to the CFML side and we watched with pride at their amazement and wonderment at how easy it was to use. However, when they asked about more information, we kinda bulked, with no real resource to point them to that would defivitely give them what they needed.
I thought about this problem. There was no reason why Open BlueDragon couldn't kick out the same type of information that JavaDoc can. The engine knows the functions and tags it is supporting. We know certain information about each of the functions/tags that would be extremely useful.
I set about the code base and after adding some annontation methods, which would allow us to insert quick snippets about a particular function/tag the automatic documentation of OpenBD started to emerge. I wrote a couple of helper methods that would allow me to dig deep into this world and produce the CFML app that would become OpenBD Docs.
The journey has started. Let me present the official resource for CFML documentation for Open BlueDragon:
- JavaDoc like interface
- Produced from the raw Java code; no external XML/wiki/sites to keep in sync
- Hot links to any particular function (CreateDateTime)
- See other functions/tags that fall in that category
- Quickly discover which parameters/attributes are optional
- Real look-ahead search
- See all functions/tags with their parameters/attributes
- Hot links to the OpenBD WIKI
- User contributed comments (Moderated)
We haven't finished annotating all the functions/methods yet, but even without that, you will find this an incredibly useful resource. I have even rediscovered functions I had completely forgotton existed!
In addition, the CFML app we developed for this, is already being bundled in the nightly build in the web-app folder. So you can even run your own internal documentation, complete with your own private notes.
We are annotating functions and tags as and when we get time, and already 80% of all the functions have been completed. For me, this is 10 years too late, for that I apologise. But we are here now. Never again will the documentation not match the implementation.
Once this has been completed, we'll update the error messages, to include the documentation for a given function inside the error report. That way you can tell instantly what is missing, or what parameter you should be using.