|
|
|
FILIGRIS WORKS is pleased to announce the release of DocFlex/Javadoc v1.2
DocFlex/Javadoc is a template-driven Javadoc doclet plus a Template Designer to it. This tool allows you to quickly design new doclets in the form of templates and generate with them Java API documentation or any other sorts of output in HTML, RTF and TXT formats. The HTML output may be both single-file and framed documentation. TXT is a plain text that can be used to generate whatever else (XML files, for instance).
The software includes two components:
The DocFlex Doclet component is also prepared separately as a freeware DocFlex/Doclet edition. All basic templates are embedded as resources into the executable jar. You can simply use this to generate the outstanding quality RTF documentation for your Java APIs (see screenshots below).
This component is the one which implements Javadoc doclet and generates Java API documentation by interpreting templates. It accepts options provided on the Javadoc command line as well as allows to specify the same options using a little GUI:
Since all content and formatting of the generated documentation now is programmed in templates, the most of options previously used to control an ordinary doclet now simply become template parameters.
The values of template parameters can be specified both on the Javadoc command line and interactively using Parameter Inspector dialog (the right screenshot -- click to enlarge). The inspector content is constructed dynamically from the parameter definitions obtained from the given template. The parameter values are displayed and edited according to their types.
The notable feature of the DocFlex Doclet is that it properly processes most of HTML tags embedded in Java comments. To generate a non-HTML output, those HTML tags need to be parsed and interpreted appropriately to the given format. DocFlex does this in some universal way for all possible non-HTML output formats it supports. Currently, this includes only RTF. The next will be XSL-FO (now in development). Almost all HTML tags (and their attributes) practically usable in doc-comments are supported now. Here's the list of all supported tags:
| Text | <b>, <strong>, <i>, <em>, <code>, <tt>, <u>, <s>, <strike>, <sub>, <sup>, <font>, <br> |
| Paragraphs | <p>, <center>, <div>, <pre>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <blockquote> |
| Lists | <ul>, <ol>, <li>, <dl>, <dt>, <dd> |
| Table | <table>, <tr>, <td>, <th> |
| Other | <hr>, <img>, <a>...</a> |
The following screenshots show pages of the RTF documentation generated by
javax.swing.text.Document interface from the Java SDK API sources
(click on the screenshot to see in full-size):
And this is the RTF generated by javax.swing.text.JTextComponent class:
Most content visible on those screenshots (including all images) was produced just by rendering of the HTML tags inserted in Java comments.
The high quality graphic Template Designer allows you to visually design your own documentation generated by Javadoc (click on the screenshot to enlarge):
Using this tool, you will be able to do most of things whose development was unimaginable so far without direct Java coding. All documentation shown in the RTF demo above was just produced by such templates without writing anything specifically for it in Java.
The Template Designer represents the whole Doclet API in the form similar to XML DOM (i.e. same as XML file) which allows to program the processing of the data provided by the Doclet API using universal approaches developed for XML (such as XPath):
The sophisticated formatting of the generated documentation is specified visually in the templates basing on abstract layout concepts such as flow of text, paragraphs, tables and lists and any combinations of them. The supported formatting features include:
The templates can be designed independently on a particular destination output format which is selected only when starting the generation. All formatting specified in templates is defined in some universal way (using formatting properties of template components) and then, rendered with the suitable features available in the selected output format.
Actually, DocFlex templates are full-blown programs. What is not visualized by the Template Designer in the form of template components can be specified in component properties using FlexQuery-expressions which are small scripts with the Java-based syntax widely used in DocFlex templates to specify all kinds of dynamically computed settings (such as dynamic properties of template components, filter conditions and so on).
See also all supported HTML tag list above.
New template parameters have been introduced for better control of the content and
formatting of the printable documentation generated by
PlainDoc.tpl
basic template:
Include/exclude details of inner classes
Controls whether inner classes should be included into the generation scope.
Include initial values of fields
Specify whether the initial values of fields should be shown in the documentation.
Omit inherited member lists for packages
Suppresses generation of lists of the inner classes, fields or methods
inherited from those classes/interfaces, which belong to the packages specified
with this parameter.
Omit all inherited member lists
Suppresses generation of all inherited member lists.
Start package from new page
Forces each package documentation to start from a new page.
Start class from new page
Forces each class documentation to start from a new page.
More than 80 built-in utility functions are fully documented now, plus the Generator Object Model (i.e. the generator variables accessible within templates) !
Those descriptions both are included in the stand-alone HTML documentation and appear in the Expression Assistant Dialog in the Template Designer.
To find a lot more information about DocFlex/Javadoc, please visit:
http://www.filigris.com/products/docflex_javadoc/
Both DocFlex/Javadoc and freeware DocFlex/Doclet editions are ready for downloads now:
http://www.filigris.com/downloads/
