LICENSE.html
|
DocFlex Software License |
README.html
|
this file |
doc/
|
DocFlex/Javadoc & DocFlex Technology Documentation |
*.bat
|
Files prepared for Windows Installation: |
designer.bat
|
|
designer-1.4.bat
|
|
generator.bat
|
|
generator-1.4.bat
|
|
update_templates.bat
|
|
linux/
|
Files prepared for Linux Installation: |
linux/designer.sh
|
|
linux/designer-1.4.sh
|
|
linux/generator.sh
|
|
linux/generator-1.4.sh
|
|
linux/update_templates.sh
|
|
linux/docflex.config
|
|
lib/
|
DocFlex/Javadoc Runtime Environment: |
lib/docflex-javadoc.jar
|
|
lib/docflex-javadoc-1.4.jar
|
|
lib/docflex.config
|
|
config/
|
Configuration files (created and updated dynamically): |
config/designer.config
|
|
config/generator.config
|
|
templates/
|
Contains the Standard Template Sets: |
templates/javadoc/
|
|
templates/javadoc-1.4/
|
|
demo/
|
Java files for demo generation: |
demo/java4/
|
|
demo/java5/
|
|
ant/
|
Ant example files: |
ant/build.xml
|
|
ant/make.bat
|
|
ant/make.sh
|
|
maven/
|
Maven 2 installation/example files (see also Running Maven Demo): |
maven/install.bat
|
|
maven/install.sh
|
|
maven/pom.xml
|
|
maven/site.bat
|
|
maven/site.sh
|
|
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 includes both MS Windows BAT files and Linux shell script files to run DocFlex/Javadoc immediately on those operating systems. See Windows Installation and Linux Installation respectively.
We were also reported that DocFlex/Javadoc worked successfully under Mac OS X.
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!
However, you may use or further modify your trial templates once you have installed a Commercial or Academic License for DocFlex/Javadoc.
In addition, the Commercial License will allow you to clear your templates created/modified in trial mode from the limitation on execution with the free edition. To do this, you should resave the templates with the Template Designer after installing the new license.
You can use update_templates.bat to upgrade all your templates at once in a batch mode.
For more details, see the Template Designer command line options
(you can use also '-?' argument in designer.bat).
*.bat files in DocFlex/Javadoc root directory
to specify the JDK variable according to the location of
JDK1.5 or JDK1.6 installed on your system.
DFH variable to the absolute pathname
of the DocFlex/Javadoc installation directory (e.g. set DFH=C:\docflex-javadoc-1.5.5).
docflex.license, which you must have
received by e-mail, to lib directory. This file should always be near
the docflex-javadoc.jar file!
designer.bat or generator.bat !
*.sh shell script files contained in linux subdirectory
to specify the JDK variable according to the location of
JDK1.5 or JDK1.6 installed on your system.
For each shell script file, edit its "Permission" properties to allow to be executed by Linux.
docflex.license, which you must have
received by e-mail, to lib directory. This file should always be near the
docflex-javadoc.jar file!
designer.sh or generator.sh !
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):
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
maven
and run install.bat. This will install DocFlex Doclet
(i.e. docflex-javadoc.jar containing its executable code)
into the Maven repository.
site.bat to generate the project web-site.
After Maven ends you will see a new 'target' subdirectory.
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.
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.
Check the latest releases and documentation updates at: www.filigris.com.
A new property has been introduced for template sections: "Break Parent Section Block".
When specified, it forces the template interpreter, after the processing of the given section, to break the further processing of the containing it section block according to the property value, which may be one of the following:
"break when section executed"
The processing of the parent block will be broken only when the given section has been executed."break when section produced output"Note: The section is executed when it has passed its enabling condition (if specified) and the current generator context element complies with the Matching Element Type(s) specified on the section.
The processing of the parent block will be broken only when the given section has not only been executed but also produced some non-empty output.In the Template Designer, when the 'Break Parent Section Block' property is specified on a section, it is indicated with a special icon, which appears on that section in the left designer pane (showing the section tree). The property itself can be specified in the "Component | Options" tab of section's property dialog.
Until now, the functionality of the new property was substituted by testing
in the enabling conditions of other sections (located below the given one) one of the generator variables:
'sectionBlock.execSecNone' or 'sectionBlock.outputSecNone'.
(Those variables allow you to test if some sections in a section block have been already executed
or produced a non-empty output.)
The old approach works as well now. However, the new one adds clarity, simplifies programming and may substantially improve performance of template applications (up to 15% in some our tests!).
The new feature is already used in the standard template set.
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.
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.
A Maven sample project has been added to demonstrate how to integrate DocFlex Doclet with Apache Maven 2.
A new licensing system has been implemented. However, this currently will not particularly affect DocFlex/Javadoc product line, except that the Template Designer will work now in demo mode without any special licensing (e.g. without a trial license).
Note: Any old commercial licenses will work the same. If you have one, you may install and use it with this version as well.
Now, the parameter group nodes may themselves serve as the template parameters. This allows making the template parameter tree even more compact (especially in the case of big template applications with lots of parameters).
This feature may not sound very great, but it was not that easy to implement. In fact, it substantially speeds up the process of designing of templates (which we particularly need ourselves as the primary users of our own tool).
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).
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.
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).
When Copy/Paste template components, the original settings of the component being copied (including those of its nested components) that are dependant on the context (e.g. the context Element Type or formatting styles) are preserved now in some "latent" form along with the copy of that component at the new location. This is done even though those settings might be senseless according to the new context at the moment of copying. (For instance, the original component may print the value of an attribute of the context element. However, at the new location the current context Element Type has no such an attribute. Hence, the component's settings about that attribute would be lost. The same is true about formatting styles.) Once at the new location the context has been changed appropriately (e.g. the needed formatting style has been copied there as well), the latent settings will be restored as actual ones. This all may save lots of time when a piece of a template is being reused at different locations or in another template (perhaps with some little changes). All the necessary context settings simply cannot be copied to the new location together with the component at once!
In addition to "Exclude By Tags", a similar group of parameters "Exclude By Annotations" has been added:
Specify annotation types by which both classes and class members (i.e. fields, constructors and methods) are completely excluded from the generated documentation.
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.
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!
In addition to the default template set (which fully supports Java 5), a reduced template set "javadoc-1.4" has been added, which is based only on the pre-Java5 features provided by Doclet API 1.4 and, because of this, is much simpler.
You can use this template set for learning or when your project is based only on Java 1.4.
Similarly the findTag() function, a new
findAnnotation() function has been added.
It finds an annotation with the specified qualified name assigned to the specified package, program element or constructor/method's parameter. For a program element (i.e. class or member), the search is extended to all classes containing/enclosing it.
This function is used in the implementation of the new "Exclude By Annotations" parameters.
It is particularly useful when some annotations specified in a class affect processing of the class' members and its inner classes. For more detail, see Template Designer | Help | Assistant | Function by Category | Javadoc | findAnnotation().
In the Element Type Tree, which shows the mapping of the Doclet API interfaces and methods onto a virtual XML document (e.g. see Template Designer | Help | Assistant | All Element Types), the child element types and attributes inherited from the ancestor types appear now in a different color. This helps to distinguish them quickly from the own children and attribute of the given type, which adds clarity to the whole representation.
The old "Exclude by tags" template parameter has been replaced with the whole three parameters:
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).
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 especially helpful when you will need next time to change your implementation while keeping intact what you have declared in your open API.
Specify tags by which only class members are selectively excluded from the generated documentation.
findTag() was added.
It finds a tag of the specified kind in the specified Doc element.
If the tag is not found and the given element is a program element (i.e. class or member),
the search is continued in all classes containing/enclosing it.
This function is used in the implementation of the new "Exclude By Tags" parameters.
It is particularly useful when some tags specified in a class affect processing of the class' members and its inner classes. For more detail, see Template Designer | Help | Assistant | Function by Category | Javadoc | findTags().
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 (see: Template Designer | File | Properties | Formatting | General | Resolution (DPI)). So, in HTML, the new image size will always be specified in pixels.
Now, all supported image formats include: GIF, PNG, JPG, WMF, BMP
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:
The following are two tests that have been run on Java SE 6 JDK Source Code (downloaded from: http://download.java.net/jdk6/) using standard 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):
|
This is the result of the generation of a single-file RTF documentation by the Java sources
of javax.swing package and subpackages:
|
align attribute of an <img> tag in
a description preformatted with HTML markup.
(See Image Control Properties Dialog | Formatting | Image tab).
OutputFormat.renderEmbeddedHTML has been added
to indicate if "Render embedded HTML" format option has been specified for the generator.
stderr (by default) or in a separate 'docflex_error.log' file
(when it is specified with the newly introduced -errlog option).
GOMIterator.prevItem and GOMIterator.nextItem
were introduced as well as a method accompanying them:
GOMIterator.itemAt().
For details, see Template Designer | Help | Expression Assistant dialog.
DocFlex/Javadoc has been tuned to support Linux (as well as Mac OS X):
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 | DocFlex Doclet | Tips | Generating RTF for OpenOffice.org
The "openURL" setting, which is contained in docflex.config
(the main DocFlex configuration file located in lib directory
near docflex-javadoc.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.
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:
|
A new template parameter "Exclude by tags" has been introduced in standard templates. This parameter allows to exclude from the generated documentation classes, fields and methods with specified tags.
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.
-launchviewer-launchviewer=falsegenerator.config
-quiet command line option.
Setting this option suppresses most of non-error generator messages.
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.
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 have been introduced for better control of the content and
formatting of the printable documentation generated by PlainDoc.tpl
standard template:
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.