DocFlex/Doclet, Version 1.5.5

Table Of Contents

• Package Contents
• Technical Requirements
• Simultaneous Support of Java 1.4 and Java 5
• Limitations of Freeware Edition
• Installation
  • Windows Installation
  • Linux Installation
• Running Maven Demo
• Getting Help
• Change Log

Package Contents

Technical Requirements

• JDK 6
• JDK 5.0
• Java2 SDK 1.4

Since DocFlex/Doclet is a pure Java application, it is supposed to work on any operating system with the installed JDK.

Specifically, the software includes both MS Windows BAT files and Linux shell script files to run DocFlex/Doclet immediately on those operating systems. See Windows Installation and Linux Installation respectively.

We were also reported that DocFlex/Doclet worked successfully under Mac OS X.

Simultaneous Support of Java 1.4 and Java 5

However, as Java 1.4 may be still in use, we have 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.

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!

Limitations of Freeware Edition

1. The freeware edition has no specific limitations on the size or content of the processed Java projects neither on the output it generates. (It just makes all the DocFlex Technology is up to.)

2. The Template Designer is not included in the freeware edition. You can neither create new templates nor modify the existing ones.

3. All necessary templates provided with the freeware edition are built into the doclet Java library file.

   However, the freeware edition allows to execute any other DocFlex templates created with a properly licensed copy of the full version of DocFlex/Javadoc.

   If you purchase a commercial license, you can create your own templates and distribute them wherever you like, so other people can use your templates with the freeware DocFlex/Doclet edition without additional charge.

Installation

Windows Installation

1. Unzip the downloaded archive.
2. Edit the generator.bat file in DocFlex/Doclet root directory to specify the JDK variable according to the location of JDK1.5 or JDK1.6 installed on your system.
3. If you want to run this file from a different location, set also the DFH variable to the absolute pathname of the DocFlex/Doclet installation directory (e.g. set DFH=C:\docflex-doclet-1.5.5).

Linux Installation

1. Unzip the downloaded archive.
2. Edit the generator.sh shell script file in linux subdirectory to specify the JDK variable according to the location of JDK1.5 or JDK1.6 installed on your system. Change "Permission" properties of this file to allow it to be executed by Linux.

Running Maven Demo

If you do not have Maven yet, download it from the Apache Maven web-site: http://maven.apache.org/. The download archive will contain exactly the Maven home directory, which you may unpack at any location (e.g. C:\apache-maven-2.0.9).

Further, please follow these steps (Windows platform):

1. Edit maven\install.bat to specify 'JAVA_HOME' and 'M2_HOME' variables according to the locations of Java and Maven 2 installed on your system. For example:

   set JAVA_HOME=C:\jdk1.6
set M2_HOME=C:\apache-maven-2.0.9

2. Switch the current directory to maven and run install.bat. This will install DocFlex Doclet (i.e. docflex-doclet.jar containing its executable code) into the Maven repository.
3. Run site.bat to generate the project web-site. After Maven ends you will see a new 'target' subdirectory.
4. Open target\site\index.html file. Then, go to "Project Reports" and click "DocFlex Doclet Demo". You will see the demo JavaDoc generated by DocFlex Doclet.

Under Linux, everything is the same except that instead of *.bat you should use *.sh command files.

Note: To pass those steps, Maven may need to download from Internet and install lots of plugins. (In fact, Maven is all made of various plugins, which it downloads from Internet dynamically as needed.) So, you must be connected to Internet during this.

Getting Help

Check the latest releases and documentation updates at: www.filigris.com.

Change Log

Version 1.5.5

• Doclet GUI

  The processing of the mouse-click events has been reworked so as to show popup menus correctly on different platforms.

  Until this version, the popup menus actually didn't work on Apple Mac (with its one-button mouse). Now, it is fixed.

• Output Generators

  The EMF image format has been supported. Now, the EMF images can be inserted both in the generated HTML and RTF documents.

  All supported (and tested) image formats now include: GIF, PNG, JPG, WMF, EMF, BMP.

• Maven Example

  A Maven sample project has been added to demonstrate how to integrate DocFlex Doclet with Apache Maven 2.

Version 1.5.4

• Template interpreter / output generator

  The format of -P and -O command-line options (which specify a value of a template parameter or output format option) has been changed slightly so as to pass the value as a separate command-line argument.

  That was needed for better compatibility with Apache Ant (particularly, in some situations when the value string contains spaces).

• Standard Template Set

  The processing of {@inheritDoc} tags has been slightly changed so as not to reprint them back in the documentation when no actual inherited comments have been found.

Version 1.5.3

• Generator GUI | Template Parameter Inspector

  As the number of template parameters (controlling what is generated) will ever grow, the Template Parameter Inspector in its previous form became increasingly cumbersome and difficult to navigate.

  We have addressed that problem by introducing a possibility to collapse/expand the parameter group nodes dynamically (some of which can be preset in the templates to appear initially in the collapsed form; further, the current collapse/expand state of particular group nodes is saved in the generator.config and restored next time). This improvement should make the whole parameter tree a lot more compact and easy to use.

  The same feature has been extended to all other property inspectors (e.g. in the Output Format Option dialogs and the Template Designer).

Version 1.5.2

• New template parameters

  In addition to "Exclude By Tags", a similar group of parameters "Exclude By Annotations" has been added:

  1. Exclude By Annotations | classes & members

     Specify annotation types by which both classes and class members (i.e. fields, constructors and methods) are completely excluded from the generated documentation.

  2. Exclude By Annotations | classes

     Allows to hide completely from the generated documentation some intermediate classes of your internal implementation, however, to preserve documenting of some their fields and methods (inherited by other classes), which are supposed to be part of an open API.

  3. Exclude By Annotations | members

     Specify annotation types by which only class members (i.e. fields, constructors and methods) are selectively excluded from the generated documentation.

  The reason why tags are not enough is that they are not retained in the compiled binary classes.

  Suppose that before generating JavaDoc, a part of your project is present already in a precompiled binary form (e.g. in a jar-file) and you want to exclude those classes from mentioning in the documentation (even though they are declared public for your internal use). You will not be able to achieve this simply by marking such classes with tags and trying to exclude by them! Those tags won't get into the binary classes and, hence, the Doclet API won't know anything about them. Annotations, on the contrary, can be retained in binary form and here is where they can help!

Version 1.5.1

• New template parameters

  The old "Exclude by tags" template parameter has been replaced with the whole three parameters:

  1. Exclude By Tags | classes & members

     Specify tags by which both classes and everything defined within them (i.e. members and inner classes) will be completely excluded from the documentation. Before this revision, the public/protected members of the excluded classes might still appear in the documentation (e.g. in such places like inherited member lists).

  2. Exclude By Tags | classes

     Allows to hide completely from the generated documentation some intermediate public classes of your internal implementation while preserving documenting their public/protected fields and methods supposed to be part of an open API.

     The effect will be that each visible inheritable member of the excluded class will appear in every direct descendant of that class being documented (as if that member was defined directly there).

     This may be particularly helpful when you will need next time to change your implementation while keeping intact what you have declared in your open API.

  3. Exclude By Tags | members

     Specify tags by which only class members are selectively excluded from the generated documentation.

• Template interpreter / output generator
  • Reworked scaling of images in HTML.

    In templates, the new image size must be specified in device-independent units (like points). Before that, it was an HTML browser who converted points into pixels, which might be responsible for producing images with unpredictable sizes.

    Now, when generating HTML, the DocFlex generator itself converts point size into pixel size according to the DPI value specified in the formatting properties of the given templates. So, in HTML, the new image size will always be specified in pixels.

  • Support of images in BMP format.

    Now, all supported image formats include: GIF, PNG, JPG, WMF, BMP

Version 1.5.0

• Full support of Java 5 language features

  The version 1.5.0 is a milestone of DocFlex/Javadoc development. Since that version, DocFlex/Javadoc fully supports all new language features introduced in Java 5. In particular, this includes two major innovations:

  1. The extension of the Doclet DSM (which maps the whole Doclet API into a DOM-like representation used in DocFlex templates) to fully cover the new Doclet API introduced since JDK 5.0.

  2. The new basic template set to generate documentation with the full support of the new language features introduced in Java 5:
     • Generic Types
     • Enumerated Types
     • Annotations

• Performance improvement

  The following are two tests that have been run on Java SE 6 JDK Source Code (downloaded from: http://download.java.net/jdk6/) using basic templates and default generator settings.

  This is the result of the generation of a framed HTML documentation by the Java sources of all java.* packages and all their subpackages (i.e. the entire Java core class library):

  Number of Java classes:   1363 Total source code size:   18.1 Mb (all files) Generation time:   194 sec Result HTML documentation:   39.7 Mb Number of generated files:   1476 Computer platform:   AMD Athlon64 3000+ based system / Windows XP JDK version:   1.6.0

  This is the result of the generation of a single-file RTF documentation by the Java sources of javax.swing package and subpackages:

  Number of Java classes:   872 Total source code size:   10.7 Mb (all files) Generation time:   189 sec Result RTF document:   22.4 Mb (with images) Number of pages (A4):   3981 Computer platform:   AMD Athlon64 3000+ based system / Windows XP JDK version:   1.6.0

Version 1.4.11

• Better support for image formatting. Now, an image can be aligned both to the left or right of a text and wrapped by it. This is supported both in HTML and RTF output. An image can be aligned directly in a template (e.g. by specifying properties of an Image Control) or using align attribute of an <img> tag in a description preformatted with HTML markup.

Version 1.4.10

• Now, the generator consumes considerably less memory and works up to 10% faster!
• The error reporting, when the generator works without GUI, is directed now to the stderr (by default) or in a separate 'docflex_error.log' file (when it is specified with the newly introduced -errlog option).

Version 1.4

• DocFlex/Doclet now supports Linux

  DocFlex/Doclet has been tuned to support Linux (as well as Mac OS X):

  • Some early bugs have been fixed, which prevented it working properly under Linux.
  • A special RTF option was introduced to generate OpenOffice.org friendly RTF (see below)
  • Improved support for external document viewers (see below)

• New RTF option

  A new RTF output option "Tune output for MS Word" has been introduced. This option, actually, allows switching off that very tuning (which until now was the default mode) to produce an RTF friendlier to open with other non MS Word applications, e.g. OpenOffice.org Writer under Linux.

  For more details, see Documentation | Using DocFlex Doclet | Tips | Generating RTF for OpenOffice.org

• Improved support for external document viewers

  The "openURL" setting, which is contained in docflex.config (the main DocFlex configuration file located in lib directory near docflex-doclet.jar) and specifies an external application launched automatically by the generator to view the generated documentation, now allows to assign different such applications for each particular document/URL type.

  For example, using this setting under Linux, you can assign directly for all RTF documents to be open with OpenOffice.org Writer and other documents -- with Firefox web browser.

  To find out how to do this, please see the instruction contained in docflex.config itself.

Version 1.3

• Performance improvement

  Thanks to implementing of a new algorithm handling cascading formatting properties of template components, the general performance of all output generators has been improved up to 30%!

  The following is the result of a single file RTF documentation generation for Java sources contained in javax.swing package and its subpackages supplied with JDK 1.4:

  Number of Java classes:   540 Total source code size:   8.2 Mb Generation time:   199 sec Result RTF document:   20.5 Mb Number of pages (A4):   3012 Computer platform:   AMD Athlon64 3000+ based system / Windows XP

• New template parameter

  A new template parameter "Exclude by tags" has been introduced in basic templates. This parameter allows to exclude from the generated documentation classes, fields and methods with specified tags.

• More command line option support
  • For any boolean command line option recognized by DocFlex/Doclet, now, its explicit true/false value can be specified directly on the command line. As it was before, when the option value is not specified, it is assumed as true.

    For example:

    -launchviewer

    Do launch viewer

    -launchviewer=false

    Do not launch viewer, no matter what's specified in the generator.config

  • DocFlex/Doclet now supports the -quiet command line option. Setting this option suppresses most of non-error generator messages.

• New HTML option

  A new HTML output option "Add Mark of the Web" has been introduced.

  Setting this option will avoid the security alert messages popping up by Microsoft Internet Explorer under Windows XP SP2 when viewing the HTML documentation generated by DocFlex.

  The new option is an alternative to using the old "HTML pattern file" option which also allows to solve this problem however in a more cumbersome way.

Version 1.2

• Full support of table tags in embedded HTML

  When a non-HTML output (such as RTF) is generated, all HTML tags embedded in Java source comments need to be parsed and interpreted with the appropriate formatting available in the destination output format. This is implemented in some universal way for all possible non-HTML formats supported by DocFlex core. (At the moment, this includes only RTF, but other formats coming.)

  Now, almost all HTML tags (and their attributes) practically usable in doc-comments are supported. Here's the list of all supported HTML 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>

• New template parameters

  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.

Version 1.1

• Upgrade with the latest DocFlex core
  • Lots of old bugs fixed
  • Performance of the generator improved -- some tests show the generator is working now about 15% faster.

• Improvements in templates
  • Some inaccuracies in templates corrected
  • Two new template parameters introduced to control omitting of package qualifiers in the generated documentation (e.g. in method parameters, result and field types, etc.)

Version 1.0

The story starts here!