Site Map   PRODUCTS ------------------------------------- DocFlex Technology    About    Key Features    Data Processing    Formatting    Templates/Template Designer    Documentaion   DocFlex/XML    About    Documentaion        Installation & Config Files        Running Generator         Designing Templates    Sample        Sales Report        Alternative to XSLT    XMLDoc        About        Templates    XSDDoc        About        Examples        Templates        FAQ    Tutorials   DocFlex/Javadoc    About    Doclet    Examples    Templates    Tutorials   DocFlex/Together    About    Examples    Basic Templates    Documentaion    Tutorials   TRY ------------------------------------- Downloads Registration Trial License   BUY ------------------------------------- Licensing/Pricing Shop   COMPANY ------------------------------------- News Products Services Customers About Us Imprint Legal    Terms of Use    Business Terms & Conditions    End User License Terms Contact Links

About DocFlex/Javadoc

1. Overview
   • Key Features
   • System Requirements
   • Simultaneous Support of Java 1.4 and Java 5
   • XML Generation
2. How does it work?
   • Doclet DSM
   • What are Templates?
   • Standard Template Set
   • Doclet GUI
3. How fast does it work?
4. Benefits to the users
5. Future Versions
   • Versions 1.6
   • Next Versions

1.  Overview

Key Features

• Full support of new Java 5.0 language features:
  • Generic Types
  • Enums
  • Annotations
• Simultaneous support of Java 1.4 and Java 5 (see below).
• The standard template set included in the software allows instant generation of
  • Framed HTML JavaDoc similar to that generated by the standard Javadoc doclet.
  • The same documentation packed into a single HTML file.
  • The exceptional quality RTF JavaDoc with the correct rendering of HTML tags embedded in Java comments (including insertion of images specified with <img> tags).
  Besides this, it is possible to exclude from the result documentation any mentioning of classes, fields and methods marked with the specified tags or annotations -- a unique capability unknown to us to be supported by any other doclet (including the standard one).
• A high quality graphic Template Designer allows visual designing of most of things which development is possible otherwise only by direct Java coding.
• The Template Designer represents the whole Doclet API in the form similar to XML DOM, which is a kind of a virtual XML document called Doclet Data Source Model (or Doclet DSM). This makes possible programming and processing of the data provided by the Doclet API using universal approaches developed for XML (such as XPath).
• The templates created with the Template Designer are interpreted by the DocFlex Doclet, an output generator implemented as a Javadoc doclet and included in the package. In effect, the templates interpreted by the DocFlex Doclet behave as if they are separate doclets themselves.

  You can freely distribute the templates created by you to anyone else and execute them with the “DocFlex/Doclet”, which is a freeware edition of DocFlex/Javadoc that includes only the DocFlex Doclet (plus the standard templates) without the Template Designer.

• Besides the possibility to specify all doclet setting using options on the Javadoc command line, DocFlex Doclet also provides a high quality Doclet GUI, where you can assign the same settings at once in a lot more user-friendly way, start the generation, track its progress and cancel it at any moment (if you wish).

  Once the generation has been finished (or cancelled), you can start it again with different settings and a new (or modified) template set. This, in effect, allows changing your doclet on the fly. You won't need to restart the whole Javadoc. All the memory representation of your Java project provided via the Doclet API will remain the same. This unique capability makes possible extremely fast designing and modification of your templates. Just change something in the Template Designer, restart the generator and you can see how it looks now in the result output!

• The current version of DocFlex Doclet generates output in the following formats:
  • HTML (version 4.0)
  • RTF  (version 1.6 - supported since Word 2000)
  • TXT  (plain text)
  The plain text output may be particularly useful for various utilizations of Java code information provided by the Doclet API (for instance, to generate XML files by it, or SQL files to import into a database).
• DocFlex/Javadoc supports numerous sophisticated formatting techniques which include
  • text formatting: fonts, colors, borders
  • paragraph formatting: margins, pagination control, borders, colors
  • border formatting: styles (solid, double, dashed, dotted), thickness, colors
  • tables: arbitrary cell layouts, borders, nested tables
  • lists: bulleted, numbered, delimited
  • document fields (RTF): page number, number of pages, TOC, etc.
  • page formatting: size, orientation, margins, headers/footers
  • formatting styles
  • rendering of embedded HTML, which means interpreting in non-HTML output formats (such as RTF) the HTML tags embedded in Java source comments. Almost all HTML tags practically usable in doc-comments are supported now. See Formatting Features | Rendering of embedded HTML for all supported HTML tags list.
• The templates can be designed independently on a particular output format, which is selected only when starting the generation. All formatting specified in templates is defined in some universal way (using properties of template components) and, then, rendered with the suitable features available in the selected output format.
• Depending on a particular template, the generated output can be
  • single-file document (all formats)
  • framed multi-file documentation (HTML only)
• The framed documentation is generated using special frameset templates. Each frameset template, among other things, contain a frameset definition that allows defining your own layout of frame windows and target the documents loaded by hyperlinks into particular frames.
• DocFlex/Javadoc is able to generate a common network of hyperlinks for the whole documentation. The generation of hyperlinks is programmed using special source- and target-keys defined in the template components. It is also possible to program loading several frame windows from a single hyperlink at once. The hyperlinks can be generated in all output formats that support them (currently, this includes HTML and RTF).
• Since all content and formatting of the generated documentation now is specified in templates, the most of options previously used to control behavior of an ordinary doclet now simply become template parameters.

  DocFlex/Javadoc provides elaborated support for template parameters. The parameters can be defined and accessed within templates to adjust the dynamic properties of template components.

  The values of template parameters can be specified both on the Javadoc command line and interactively using Parameter Inspector dialog invoked from the Doclet GUI provided by the DocFlex Doclet.

System Requirements

• JDK 6
• JDK 5.0
• Java2 SDK 1.4

Since DocFlex/Javadoc is a pure Java application (the Template Designer GUI is based entirely on Swing), it is supposed to work on any operating system with the installed JDK.

Specifically, the software available for downloads includes both MS Windows BAT files and Linux shell script files to run DocFlex/Javadoc immediately on those operating systems. (We have been also reported that DocFlex/Javadoc was successfully working under Mac OS X). Additionally, a sample Ant buildfile is provided to demonstrate integration of DocFlex Doclet with the Apache Ant.

For further details, please see product README files on the downloads page.

Simultaneous Support of Java 1.4 and Java 5

However, as we found (after the preliminary v1.5 beta release), Java 1.4 appears to be still well in use. So, we have finally decided in DocFlex/Javadoc v1.5.x to support both Java versions (i.e. the new Doclet API 1.5 and the old Doclet API 1.4).

Since the binaries compiled for Java 5 are not compatible with Java 1.4, now, DocFlex/Javadoc v1.5.x (both editions) includes two Java libraries: the one compiled for Java 5+ and another one compiled for Java 1.4.

The Doclet DSM, on which any DocFlex/Javadoc templates are based, is always the same. That is, the Java 5 functionality (i.e. the mapping of entire Doclet API 1.5 on a virtual XML document model) is present in both libraries. However, in the version compiled for Java 1.4, everything concerned Java 5 is emulated by the Doclet DSM Driver itself.

It happened to be very simple to implement. So, we've done this!

As a result, any templates designed for either Java version will work fine under both Java 5+ and Java 1.4 as well. The templates simply won't "notice" the difference!

XML Generation

To generated XML, all you need is to design a template where the output produced by Data Controls (from the data obtained from Doclet API) is interchanged with the static text representing certain XML tags, which can be produced, for instance, by Label Controls. Then, you can simply generate a TXT output with such a template, and this will be XML.

Since generating XML is a very general topic (first, you need to choose what a specification that XML should follow), we have not found yet any particular application where an XML generated with Javadoc would be of mass interest (except XSL-FO, which is a special case). Therefore, we do not provide any templates specifically designed to generated XML.

However, if you could suggest such an application, just let us know by sending a e-mail to: support@docflex.com. If your idea fits a certain known XML standard, we could quickly design templates for that application and supplement with them the provided standard templates as well as the freeware edition -- DocFlex/Doclet.

2.  How does it work?

The DocFlex/Javadoc implementation consists of four major components:

1. The Doclet DSM Driver, which represents a bridge between Javadoc Doclet API and DocFlex core. The driver connects to Javadoc using Doclet API and supplies data via DSM (Data Source Model) interface that is a representation of Javadoc data source in the form understandable for DocFlex core. This representation is called Doclet DSM. The driver also supports DSM Type interface which provides the data structure and type information about this data source. The DSM interface is used by DocFlex Generator to obtain data it operates. The DSM Type interface is used both by the generator to know how to handle those data, and by the Template Designer to provide data type information during template design.
2. The DocFlex Doclet component, which provides com.docflex.javadoc.Doclet class that is the one to be specified with the -doclet option on the Javadoc command line. The Doclet component handles command line options received from Javadoc, initiates Doclet DSM Driver and starts the generator. It also may invoke the Doclet GUI, which provides a user-friendly interface to specify most of parameters and settings used by the generator. See DocFlex Doclet page for more information on this topic.
3. The DocFlex Generator, which is launched by DocFlex Doclet and receives from it:
   • The Doclet DSM Driver ready to supply data from Javadoc
   • The template to be interpreted
   • The template parameters and other settings
   The generator executes the template and generates the output documentation.
4. The Template Designer, which provides a GUI for designing the templates. It also starts Doclet DSM Driver (however, without connection to Javadoc) and uses information provided by DSM Type interface. In the next section, we shall discuss what that information is.

   

Doclet DSM

However, one can notice that the structure of that information is very much similar to that described by DOM. All data provided by Doclet API can be presented either as some XML elements or as their attributes.

Doclet DSM Driver makes use of this. It maps all Doclet API classes (such as com.sun.javadoc.RootDoc, com.sun.javadoc.ClassDoc and so on) to the equally named XML elements.

The methods of Doclet API classes (or more precisely, the data they return) are mapped according to the following rules:

• If a method returns one or more objects whose type has an aggregation relationship with the given class (i.e. the returned objects are part of an object of this class) and, in addition, the method returns all aggregated objects of such type, then the returned objects are interpreted as children of the XML element associated with the given class.

  For example, class com.sun.javadoc.ClassDoc has a method methods(), which returns an array of com.sun.javadoc.FieldDoc objects representing all fields of a Java class being documented. Those two classes and method are mapped as the following:

  1. Class com.sun.javadoc.ClassDoc is mapped to XML element ClassDoc
  2. Class com.sun.javadoc.FieldDoc is mapped to XML element FieldDoc
  3. Method ClassDoc.fields() is mapped into parent/child relationship between ClassDoc and FieldDoc elements according to the following XML DTD declaration:

     <!ELEMENT ClassDoc (FieldDoc*)>

• If a method returns object(s) whose type has an association relationship with the given class, or in the case of aggregation, the returned array represents only a subset of all aggregated objects of this type, then this method is mapped as an attribute with IDREF or IDREFS type (depending on the cardinality of the returned objects).

  For example, method com.sun.javadoc.ClassDoc.interfaces() returns ClassDoc objects, which represent all interfaces implemented by a documented Java class. Those interfaces are not part of this class. They exist independently. So, the relationship between the interfaces and the class implementing them should be interpreted (in our context) as an association. Therefore, the method ClassDoc.interfaces() is mapped as an attribute interfaces of the ClassDoc XML element. Here is how this is presented in the form of XML DTD declaration:

  <!ATTRLIST ClassDoc interfaces IDREFS>

• If a method returns a primitive type it is mapped as an attribute of the XML element associated with the given class. The attribute data type is the same as the one returned by the method. (Note: DocFlex introduces additional data types not presented in XML DTD to handle values of XML elements and attributes suitable for Java-based data sources.)

  For example, method com.sun.javadoc.ClassDoc.isAbstract(), which returns a boolean value, is mapped as isAbstact attribute of the ClassDoc XML element. Here is how this would looks in the form of XML DTD declaration (if BOOLEAN data type was allowed in DTD):

  <!ATTRLIST ClassDoc isAbstract BOOLEAN>

What are Templates?

If you consider how almost any Java library that generates something (and not only generates -- for instance, powers a GUI system) works, you will notice that, basically, it may be described as the following:

1. First, we need to create a certain object representation of some controlling structure (using special classes and methods of that library).
2. Further, we call an interpreter included in that library and pass to it that controlling structure along with some data source we want to process, e.g. some data file, some interface or whatsoever. (Actually, such an interpreter may be started just by calling some member method of the root object representing that controlling structure. For instance, in case of a GUI system, this may be as simple as dlg.show()).
3. Finally, the interpreter processes that controlling structure and produces from the data source some useful output (or shows a GUI).

Now, let's imagine that such a controlling structure is serialized to a file (and, therefore, can be created from it). What is that file, then? One may call it a “template”!

But if that is a template, why not to create and edit it using some template designer GUI? That approach has a number of advantages:

• A designer GUI can visualize everything. Now, rather than coding abstract method calls, we can visually construct the controlling structure using the notions of things that we expect to see in the generated output.
• Since probably every modern document format in its core is based on the same obvious concepts like flows of text with specified fonts and colors, paragraphs with specified margins, borders and other properties, tables, bulleted/numbered lists, images and so on, most of such things can be defined in some universal format-independent way, which can be encoded in the form of template components.
• Such template components can be visualized in the template designer GUI. This allows easy manipulation with them (creating/defining, modifying, moving, coping and so on). Doing the same by calling various Java methods and modifying Java code each time we need to change something would be a lot more cumbersome!
• On other hand, the template interpreter will render those template components with the suitable features of the particular destination output format (such as HTML or RTF). So, we can be relieved from learning and programming lots of very complicated (and sometimes poorly documented) things specific to a particular format. Instead, we can more concentrate on our primary application task.
• The template designer (to a large degree) ensures that the result controlling structure (the template) is valid. That is, it won't hang when interpreted and will produce some output anyway.

The following screenshot shows the class.tpl template open in the Template Designer (click to enlarge):

Standard Template Set

Another unique feature supported by the standard template set (and not available in the standard Javadoc) is a possibility to exclude from the generated documentation the classes, fields and methods marked with special tags and annotations. This gives you incredible flexibility over how you can document your Java project!

Here is an example of the framed HTML documentation generated with the standard template set (click to see the real HTML):

Currently, the standard template set consists of only 15 template files (plus one icon), which in total occupy 390 KB. That is all what was needed to program the entire Java API documentation generator!

In comparison, the recent Java implementation of the Javadoc's standard HTML doclet (whose Java sources can be found, for instance, at http://download.java.net/jdk6/ -> jdk-6u2-fcs-src-b05-jrl-22_jun_2007.jar -> j2se/src/share/classes/com/sun/tools/doclets/) consists of 141 files occupying 979 KB in total.

What's more, unlike the standard doclet's Java sources, all templates provided with DocFlex/Javadoc are free for any changes and modifications. Using the Template Designer, you can easily change the look & feel of the generated JavaDoc, insert your company's logotype and so on, as well as to program eventually whatever you wish (so much as you are willing to understand how everything works). Further, you will be free to use your created/modified templates for whatever purpose you need.

For more details about the standard template set please see: DocFlex/Javadoc | Templates

Doclet GUI

• The main template
• The template parameters
• The output format
• The format-specific options to the output generator
• The output destination (directory/file)

When no -nodialog option has been specified on the command line, as soon as Javadoc finishes parsing Java sources and calls the doclet to generate the output, the DocFlex Doclet invokes the following dialog (click to enlarge):

The additional settings, such as template parameters and the output format options can be assigned in the special property inspector dialogs invoked by clicking the buttons on the right (click to enlarge):

When all settings are prepared, you can start the generation by clicking <Run> button. Then, the generator dialog will transform itself to show the generation progress (click to enlarge):

Once the generation has finished (or cancelled), the generator dialog transforms itself back into its initial state.

After that, you can change any settings and start the generator again with a new (or modified) template set. This, in effect, allows changing your doclet on the fly. At that, you won't need to restart the whole Javadoc. All the memory representation of your Java project provided via the Doclet API will remain the same.

This unique capability makes possible extremely fast designing and modification of your templates. Just change something in the Template Designer, restart the generator and you can see how it looks now in the result output!

For more details about the Doclet GUI please see: DocFlex/Javadoc | Doclet | Doclet GUI

3.  How fast does it work?

Now, by its performance, the result doclet (i.e. DocFlex Doclet + templates) may well rival with anything written directly in Java!

Here are a couple of tests that have been run on Java SE 6u2 JDK Source Code (downloaded from: http://download.java.net/jdk6/) using standard templates and default generator settings.

Generation of Framed HTML Documentation

Number of Java classes:   4119 Number of packages:   210 Total source code size:   41.5 Mb (all files) Generation time:   382 sec Result HTML documentation:   106 Mb Number of generated files:   4544 Computer platform:   Intel Core 2 Duo E6600 based system / Windows XP JDK version:   1.6.0_02 DocFlex/Doclet version:   1.5.2

Generation of RTF Documentation

Number of Java classes:   872 Total source code size:   10.7 Mb (all files) Generation time:   102 sec Result RTF document:   24.9 Mb (with images) Number of pages (A4):   3977 Computer platform:   Intel Core 2 Duo E6600 based system / Windows XP JDK version:   1.6.0_02 DocFlex/Doclet version:   1.5.2

4.  Benefits to the users

• The ability to visually design your own documentation generated by Javadoc using only the DocFlex Template Designer without direct programming of any doclets in Java.

  This can greatly reduce any your efforts in achieving a desirable result. At the same time, the sophistication of informative content and formatting of such documentation will not be less (but we believe, in most cases even greater) than that possible to achieve with the manual Java programming.

  That is because you will not be required to learn lots of complicated things and to overcome myriads of obstacles before achieving a substantial result -- the normal way when starting anything serious from scratch. The authors of DocFlex Technology have already passed this way and will share that result with you.

  If you, anyway, need to do some rare things that are not supported by DocFlex directly, you will be free to do whatever you like since you can build into the DocFlex templates calls to your own Java classes and easily exchange data between them and those templates.

• The ability to generate your documentation in any output format supported by DocFlex.

  When designing your documentation templates, you will not be needed to bother much about specifics of any particular output format (which may be very complicated indeed). DocFlex will render your templates in any output format it supports with the best features available in that format.

  Moreover, we are constantly working on implementing new output formats as well as improving the existing implementations. So, once you have created your templates, you could constantly improve the quality and diversity of your documentation virtually without doing anything at all. The only what you would need is to obtain new versions of DocFlex!

5.  Future Versions

Versions 1.6

1. A new template component will be added: Include Text Control. This component will allow including dynamically into the generated documentation the content of any external plain-text or pre-formatted HTML files by specified URLs or local pathnames.
2. The support in the framed HTML documentation such features as Navigation Menu, Class Hierarchy and Index. Eventually, the goal is to be able to generated with only DocFlex templates the HTML JavaDoc looking identical to the one currently generated by the Standard Doclet.
3. The open Java API that will allow extending the DocFlex templates with custom Java classes (more precisely, calling those classes from the templates). This will allow you to do such things like:
   • Including dynamically generated images into the documentation (such as class diagrams with hyperlinks and so on).
   • Analysing pieces of Java code and including into the generated documentation the information not provided directly by the Doclet API (such as marked fragments of the Java code).

Next Versions

1. First of all, we are going to support a new major output format. Most likely, this will be the direct generation of PDF output.

   We have been also considering to generate XSL-FO output instead. This is much easier to implement and, in theory, would provide a capability to generate PDF, PostScript, SVG, TeX and other formats automatically using freeware XSL-FO converters. The problem is that we are not sure about the output quality possible to achieve with those freeware converters. At the moment, it seems, there are very few of them. Good commercial ones do exist but the prices may be prohibitive for the users... If you have any considerations about this topic, please share with us!

2. Improvements of Template Designer, such as
   • drag-and-drop of template components with mouse
   • "Undo" functionality
3. Self-documenting templates (i.e. a set of templates to document any other DocFlex templates).
4. Finally, we always keep in mind that there is such a thing called Eclipse, where the whole our technology (in particular, the Template Designer) eventually is going to be.

If you are interested in any other features to be supported, please do not hesitate to send us your feature request to: support@docflex.com. We are always happy to hear your opinion, no matter whether you are registered DocFlex/Javadoc user or not!

Moreover, depending of what feature you need, we will try to figure out how to implement this right now. So, it's quite possible you could see your feature just in a few days within the next minor update!