- The Essence of Fusedoc
- Tools for Fusedoc
- Fusedoc in Applications
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Tools for Fusedoc
The current specification for Fusedoc defines Fusedoc as an XML vocabulary. Note that whereas Fusebox is currently in version 3, Fusedoc is in version 2. This is because Fusedoc is a standard that is independent of the Fusebox standard. The Fusedoc standard is only concerned with the creation of code documentation blocks known as Fusedocs.
Fusedoc Creation Tools
Fusedoc 2.0 is based on open standards. This means it is much easier to build tools to assist in the creation of Fusedocs than it was when the standard was proprietary. The first of these tools is the set of Fusedoc VTML extensions that Steve Nelson and Hal Helms created.
The Fusedoc VTML extensions provide tag completion tips and Fusedoc help for ColdFusion Studio. They are available at fusebox.org.
The installation for the VTML extensions is fairly straightforward; if you follow the readme files, you shouldn't have trouble. You must unpack a zipped archive to specific locations within the ColdFusion Studio directory structure and edit a couple of Studio's configuration files. After the extensions are installed, you will get tag completion and help for Fusedocs.
Thanks to Fusedoc's tag basis and ColdFusion Studio's extensibility, the potential exists for more sophisticated tools to assist in creating Fusedocs. There should be non-ColdFusion Studio-based tools appearing as well.
Fusedoc's XML-based design makes it amenable to far more than just creation tools, though. The real power of Fusedocs starts to show when their standard nature is tapped within the scope of the application development.
Fusedoc-Based Tools
The XML specification provides a way to create custom tag-based vocabularies for the purpose of communicating rich data. Because this is precisely the purpose of Fusedoc, XML is a good fit, using the Fusedoc DTD.
The purpose of having a DTD is to provide the ability to validate a Fusedoc. The XML world refers to any given XML dataset with two qualities: well formedness and validity. An XML dataset is said to be well formed if its tags meet the requirements of XML. For example, all tags must be closed, either by a closing tag or an ending slash. These tags are well formed:
<mytag /> <mytag></mytag>
This one is not:
<mytag>
The preceding tag is not well formed because it is not closed. (Note the lack of a closing tag or ending slash.) Well formedness has nothing to do with the particular vocabulary, only with how the tags are formed.
Validity, however, is concerned with the specific vocabulary. To be valid, an XML dataset must contain only those tags and attributes that are allowed for its vocabulary. This is where the DTD comes in. The XML dataset has an attribute that references the DTD for its vocabulary. A validating parser can then check the contents of the dataset against the DTD to ensure that only allowable elements are used.
Most users of Fusedoc will not concern themselves with actually parsing the Fusedoc or validating its XML. Validity will be a concern only for those who are interested in taking advantage of Fusedoc through the use of utilities that read and interpret Fusedocs. Every writer of Fusedocs needs to be concerned with form, though; if a Fusedoc is not well formed, these same utilities cannot use it.
With well-formed Fusedocs available as XML data, we are open to a whole new world of tools based on the wealth of information that is available through them. The next sections discuss Harness, a tool for generating test harnesses from Fusedocs, and other tools that take advantage of the existence of Fusedocs.
Harness
The first tool to take advantage of Fusedoc as a standard was Harness, by Jeff Peters (http://www.grokfusebox.com). Harness was able to generate test harnesses for every fuse that had a Fusedoc. It could recurse (travel through every branch of) an application's directory tree to make sure every fuse got a test harness. More details of unit testing with test harnesses can be found in Fusebox: Developing ColdFusion Applications by New Riders.
Harness 2.0 is constructed to read 2.0-compliant Fusedocs. It is much more robust than the original. Harness 2.0 is a custom tag that uses the SOXML parser to handle the XML chores. If you have SOXML installed, then all you do to install Harness is copy it to your CustomTags directory.
After Harness is on your machine, all you need to run it is a simple calling file, usually named HarCall.cfm, as shown in Listing 2.
Listing 2—HarCall.cfm
<cf_harness verbose="yes"
rootDir=
Ë"#GetDirectoryFromPath(GetCurrentTemplatePath())#">
The output from running Harness in verbose mode prints a line for each test harness that is written and is organized according to the directory structure. It makes a good checklist for unit testing as well; as you run the test harness for each fuse and verify its capability, you can check it off on the printed output from Harness.
Future Tools
Considering the recursive nature of Harness, other Fusedoc-reading utilities are easy to imagine. For instance, consider a tool that would read all the Fusedocs in a project and return a report with all the <history> and <note> elements interpreted as a development progress report, with metrics for percentage of fuses waiting to be coded, in coding, and completed.
How about a tool to read Fusedocs and find out which query fuses have a <recordset> element in their <out> sections?
Perhaps we need to know which fuses were missed when some new circuits were brought in and the local standard variables were added to their fuses. An automated tool's quick cruise of the Fusedocs could give us this information.
These tasks are not only possible, but they are also comparatively simple with the XML-based power of Fusedoc 2.0. We strongly encourage you to become familiar with Fusedoc and then start thinking about how you could improve your own development processes by leveraging XML and Fusedoc. You can get started with XML parsers, such as Site Objects' SOXML ColdFusion tags (http://www.siteobjects.com) and the Torchbox effort (http://www.torchbox.com), which are good launching points for working with Fusedoc XML. You can also use Microsoft's MSXML library (http://msdn.microsoft.com) if you need to use a COM object, or CFDev.com's Java-based XML parser (http://www.cfdev.com).
Our final section in this article will look at how to go about using Fusedocs in the application-development process.