A Sample of DocJet's Output
What am I looking at?
This is the documentation that ships with the DocJet SDK; it describes
DocJet's published interfaces. People use this API for a variety of
reasons - for example, people might use this API if they have source code written
in a language that DocJet does not support.
Is there anything in particular I should take note of?
- The first thing you should notice when paging through the IDL file is
how utterly ordinary the code and comments look. The comments are just
as readable in the code as they are in the finished documentation.
Comments written in a markup language are considerably harder to write
and harder to read when looking at the code.
- The comment writer doesn't have to do anything special to create a
hyperlink - they need only use the name of an object to have it appear
as a hyperlink in the output. You can refer to design documents and
overviews from the comment in the same way - just mention the title of
the document in a comment. The design overviews can link back into the
code just as easily - by mentioning the name of an object.
- Even thought the comments do look rather ordinary, there are some small
touches that spruce up the output. For instance, if you write something in
"quotes", it is automatically translated into “stylized
left and right quotes”. DocJet can also identify code blocks if you
indent them more deeply than the standard run of your code. Also note that
some objects (e.g. IObjectCollection::GetNextOverload) contain an "Example:"
section in the comment that is rendered as preformatted text in the output.
This is yet another of DocJet's heuristic rules: it knows that most of the
time a comment section labeled "Example" is a block of source code.
- About the only allowance
that is made to DocJet are comment lines that look like "
// {group:...}".
Those lines map the object into the table of contents. DocJet supports a
variety of ways to make this mapping, several of which don't require any
change to the code to make happen. Whle the {group} directive mechanism that
is used in this example does require a change to the code, it is straightforward
and relatively easy to maintain.
Where do all the supporting pages like the "Design Overview" come from?
DocJet stores all table-of-contents related information in the "External Sources Specification"
that sits alongside your project configuration file. In this project, it made the
most sense to have the full text of the design documents and other overview topics
stored within the external source specification (.djx) file. You could also create
HTML files and attach these to your project through the .djx file as well.
To take a look at what we did, open the Windows Explorer to the directory where
you installed DocJet. Look in the "include" sub-directory to find
"IDL Documentation.djx".
How can I generate this output on my own machine?
The sample we have here is one that you can generate yourself with a demonstration
license. The source material necessary to create this documentation comes with the
standard DocJet package. (You don't need to download the SDK or anything.)
To generate this document on your own machine, you need to follow these steps:
- Open up a command prompt.
- CD to wherever you installed DocJet (
C:\Program Files\TallTree\DocJet is the default.)
- CD to the
include subdirectory
- Run
..\Program\generator.exe -v -t "IDL Documentation.djt"
If you want to play around with this sample and not mess up your DocJet installation,
the thing to do is create a new directory beside "include" and copy these files into it:
docjet_idl.idlIDL Documentation.djtIDL Documentation.djx
