The Doclet DSM Driver that maps dynamically the entire Javadoc Doclet API onto a virtual XML DOM-like representation called Doclet DSM, on which all templates and their processing is based, has been completely reworked to represent the new Doclet API (introduced since Java 9).
Unlike the old one, the new Doclet API is essentially a loose collection of various standard Java APIs mostly related to the Java compiler and its internal representation of Java code and doc-comments. The jdk.javadoc module itself is just the entry point into those APIs. It was a huge work to construct from all that a single dynamic DOM-like representation!
Everything that the standard Javadoc (i.e. Standard Doclet) can be equally processed/documented with the FlexDoc Doclet, which is a template processor / output generator framed as a Javadoc doclet.
All Java versions since 11 are supported (including the recently released Java 20).
«JavadocClassic» is a basic template that comes with FlexDoc/Javadoc. It implements a powerful Java API documentation generator that does almost everything as the standard modern Javadoc. Besides framed multi-file HTML documentation, it generates the same content also as single-file HTML and RTF.
The '??' operator has been supported interpreted as follows:
A ?? B ≡ (A != null) ? A : B
A is a string, the interpretation is slightly different:
A ?? B ≡ (A != "") ? A : B
For numeric arguments, where A must be a numeric property or variable:
A += B ≡ A = A + BA -= B ≡ A = A - B
A += B ≡ A = A + BA must be a string property or variable
The function-call-like operator has been introduced to allow the creation of typed arrays
type[] (expr1, expr2, ..., exprN)
type is the name of a particular type (e.g. String, Integer, GOMElement)expr1,...,exprN are the expressions returning the corresponding array elements
Several new FlexQuery functions have been added:
asMemberOf(),
checkHyperTarget(),
collectAttrValues(),
collectValuesByElements(),
collectValuesByLPath(),
containsWhitespace(),
convertElements(),
convertList(),
convertToEnum(),
copyDocFile(),
createElementRelation(),
filterElementGroupsByKey(),
findStyle(),
getRelatedAttrValue(),
hasBlockTag(),
hasExternalDocURL(),
isNumber(),
isUniqueSortingKey(),
iterateElements(),
NamedValue(),
newCustomElement(),
parseStringList(),
parseTokenList(),
searchBackward(),
splitCamelCase(),
switch(),
SwitchCase(),
toSegmentedSortingKey()
More details can be found in: Template Designer | Help | Assistant | Functions
Generator Object Model (GOM) properties expose in FlexQuery expressions some of the inner working of the Template Processor / Output Generator so as that can be tracked and used in templates.
The following new GOM properties have been added:GOMIterator.numElements,
GOMIterator.firstItem,
GOMIterator.lastItem,
GOMIterator.isUniqueSortingKey,
GOMOutputInfo.isDocument,
GOMOutputInfo.pageOrientation,
OutputFormat.isHTML
Custom Elements allow you to create structured chunks of data that look the same as ordinary DSM elements coming from the main data source (i.e. Doclet API). Thereby, they can be manipulated together with the ordinary elements and using the same template functionality (e.g. iterated, sorted, grouped etc).
Now, it is possible to define the specific custom element types that can be assigned to the newly created custom elements. That helps even more to utilize various element processing features of template components for custom elements as well, while making the template easier to understand.
Custom element types are defined in a special JSON file that comes along with the template set. They are injected into the
Doclet DSM Type
through the .dsmtype configuration file found in the template set folder
and appear in FlexQuery Assistance Dialog invoked in the
Template Designer (e.g. via the main menu: Help | Assistant)
with the names start with '#'.
More details about custom elements can be found in: Template Designer | Help | Assistant | Functions | By Category | Elements / Attributes | Custom Elements
Element relations allow you to extend dynamically some DSM elements
with the attributes taken from other elements.
Element relations are available only in FlexQuery expressions using the new functions:
createElementRelation(), getRelatedAttrValue().
More details can be found in: Template Designer | Help | Assistant | Functions | By Category | Elements / Attributes | Element Maps | createElementRelation()
Fitering elements by key means that each element is associated with a certain filtering key produced by that element. The result enumeration will contain only those elements whose filtering keys are unique. Those elements from the source enumeration whose filtering keys repeate are excluded.
Now, that concept is extended to a more complex case. It takes into account that those DSM elements from the source enumeration, which produce the same filtering key, may belong also to a certain "protected" group so that all such elements must get into the result enumeration anyway. That is, filtering by keys within the same group must be suppressed. Such groups, in turn, are defined by yet another group key equally calculated for each element. When group keys are the same, the elements belong to the same group.
That new filtering concept helps easily to resolve various situations without any specific extra programming. It is implemented both in the settings of
Element Iterator sections and as the FlexQuery function:
filterElementGroupsByKey()
Now, that is supported on the level of new formatting properties of template components and styles:
: boolean: color: color
Table
Previously, the entire table must have been defined only in such a single template section (with the table output style).
Stock-sections are stand-alone template sections that can be called from multiple locations in the template as if they are originally defined there (including also from themselves). Stock-sections are analogous to procedures in ordinary programming languages.
To have a stock-section generate table rows, its output style should be specified as:Table Rows
This new feature allows you to vary the table structure dynamically, especially when it is driven by the data the table represents.
Previously, a formatting style could be assigned to a template component only once statically. If the same component had to be rendered with a different style, its copy must have been created assigned with that different style. Then, the enabling conditions were specified on both components to activate only one of them at the appropriate time.
For instance, suppose that a Java class name needs to be styled with italic when that class is an interface. We create a style 'Interface' with the italic
formatting property. Then, in the properties of the component generating the class name, now we can specify:
<expr>getAttrBooleanValue("isInterface") ? findStyle ("Interface") : null
'Interface'.
Otherwise, the default styling is used.
Similarly, it can be specified at any other locations where formatting styles are used.
As the HTML markup in Java doc-comments becomes more sophisticated, now the JDK API source code uses CSS classes to style various things. But HTML tags and CSS rules cannot be interpreted directly in a non-HTML output like RTF.
Now, FlexDoc/Javadoc can employ for that the already existing functionality and to render CSS classes using template formatting styles. For more details, please see:To facilitate the restructuring of template applications (e.g. deriving new from the existing ones), new powerful tools for searching a template for various things have been implemented:
| Search For | Search Results |
|---|---|
| Line number in template file *) |
The smallest template feature (e.g. template component, Location Rule, FlexQuery expression etc.), whose definition in the template file contains this line.
This type of search is helpful to quickly find the template locations reported in the generator error diagnostics
|
| Use of function |
The list of all FlexQuery functions called in all FlexQuery expressions across the template, and for each of them, the tree of template locations, where the given function is used.
When a function is not found (e.g. it is misspelled or undefined in the given context), it will still appear in the found function list,
however, highlighted with
|
| Use of property |
The list of all Generator Object Model (GOM) properties (like iterator.numItems) set/retrieved in all FlexQuery expressions across the template,
and for each of them, the tree of template locations, where the given property is used.
When a property is not found (e.g. it is misspelled or undefined in the given context), it will still appear in the list, however, highlighted with
|
| Use of stock-section *) |
The list of all stock-sections used anywhere across the template, and for each of them, the tree of template locations, where the given stock-section is called from.
|
| Use of template parameter *) |
The list of all template parameters accessed (retrieved) in all FlexQuery expressions across the template, and for each of them,
the tree of template locations, where the given parameter is accessed.
When a parameter is not found (e.g. it is misspelled or undefined in this template), it will still appear in the found parameter list,
however, highlighted with
|
| Use of template | The list of all templates (file names) called from this template, and for each of them, the tree of template locations (i.e. Call Template sections/controls), where the given called template is specified. |
| Use of style *) |
The list of all formatting styles
used in the template, and for each of them, the tree of template locations, where the given style is used.
|
| Use of element type |
The list of all Element Types used in the template, and for each of them, the tree of template locations, where the given Element Type is used.
|
| Use of element attribute |
The list of all Element Type's attributes used in the template, and for each of them, the tree of template locations, where given attribute is used.
|
| Use of service attribute | The list of all service attributes set/retrieved in the template, and for each of them, the tree of template locations, where given service attribute is used. |
| Use of element map |
The list of all element maps (i.e. their identifiers) used in the template,
and for each of them, the tree of template locations, where the given element map is accessed.
|
| Use of element relation | The list of all element relations (i.e. their identifiers) used in the template, and for each of them, the tree of template locations, where the given element relation is accessed. |
| Use of user variable |
The list of all user variables set/retrieved in the template,
and for each of them, the tree of template locations, where the given user variable is accessed.
|
| Use of local variable |
The list of all local variables assigned/accessed in the template,
and for each of them, the tree of template locations, where the given local variable is used.
Local variables are those used in particular FlexQuery expressions. The scope of a local variable is limited to that expression.
However, equally named local variables may be used elsewhere. The local variable names may carry some meaning.
So, it may be useful to find all of them with a particular name.
|
| All disabled components/settings | All disabled components and other template locations where there are any disabled settings (e.g. hyperlink/target definitions, style overrides, location rules etc.) |
| All hypertext links and targets *) | All hypertext link/target definitions found in the template. |
| All specified expressions *) | All template locations where there are specified FlexQuery expressions. |
| All specified formatting properties | All formatting properties of template components or formatting styles found in the template that have specified values. |
| All string constants | The list of all string constants specified in all FlexQuery expressions across in this template, and for each of them, the tree of template locations where that string is used. |
| All text labels and separators |
The list of all text labels and separators specified across in this template, and for each of them,
the tree of template locations where that label/separator is used.
The text labels/separators are just another type of string constants, however, specified not in FlexQuery expression
but rather in properties of template components (e.g. Text Controls).
|
*) These search criteria were supported before, but now they have been reimplemented and enhanced to find all lost (misspelled/undefined) things.
All found template locations are shown in the form of a tree (including all parent components), from where you can easily jump to the actual template components in Template Designer.
When several matching locations are found within the same FlexQuery expression, the counter of those instances will be shown by the node representing that expression in the template location tree. Further, all found instances can be viewed in details via «View Expression...» item in the local menu invoked from that node.
The search dialog is invoked from the Template Designer main menu > Edit > Find... item. Besides that, the same search can be run from the local menu for a selected template parameter, formatting style or stock-section at their definitions.
It was also supported that when the search dialog is closed, all its current state (including the selected search criteria, the selected found item, the selected node in the template location tree) is saved and restored back into approximately the same state (or the closest one), when the search dialog is invoked again. That allows you quickly to visit all found items / template locations one after another so as to edit them (or do something else).
The generation of HTML output in relative units mode (which is the default one) has been reimplemented and switched to ‘rem’ units that are interpreted against the base font size (determined by the HTML browser).
Relative units are preferable because they allow you to smoothly adjust the text size and everything related to it by changing only the base font size in your browser settings, instead of zooming everything, which equally affects images. That will work more reliably in various situations.
Previously, relative units mode was implemented using such units like ‘em’ and ‘%’, which are based on the context font size. When HTML output was generated automatically, that was prone to various accumulation effects, which required meticulous efforts to track them as well as various tricks to reset the context font size to the base one.
Fortunately, now, all web-browsers support ‘rem’ units, which allows us to get rid of all that trouble and to reduce the generated HTML.As the descriptions found in Java doc-comments now can be styled with CSS classes specified in some custom CSS files, a possiblity has been implemented to specify such extra CSS files to the generator.
In the generator dialog, on the step of selecting HTML format, click «Options» button and in the HTML Options dialog that appears, specify:
Those CSS files will be copied into the documentation destination (associated files) directory, and links to them are inserted in every generated HTML document, e.g.
<link rel="stylesheet" type="text/css" href="../custom.css">
The algorithm of wrapping of long non-breaking strings in tables has been improved.
The only way to deal with that situation was to break such strings artificially by inserting new-lines. However, to do it properly and reliably, the whole table must be laid out beforehand (that is somehow estimated, how MS Word would do it).
Fortunately, since circa 2010, MS Word does provide a special 'Non-Width Optional Break' character, using which you can insert a hint, where the string may be broken, when it needs to be wrapped. This, however, still doesn't solve the problem completely, because the result table must look balanced, so that some of its columns do not degenerate into nonsensible width.
What was added now is that when 'Use optional breaks' option is specified and a non-breaking strings exceeds the 'Maximal unbroken length', all non-letter-or-digit characters that follow that length are appended with the 'Non-Width Optional Break'. Then, the wrapping of such a string will look smarter.
The integration of FlexDoc Doclet with the Gradle Build Tool has been worked out.
You can use FlexDoc/Javadoc with Gradle the same as with Ant and Maven.
For more information, please see:{flexdoc-javadoc}/integrations/gradle/For the purpose of better visibility of our software in Internet and promotion, we have made some renaming and relocation with the following effects:
You can equally install any your old license for DocFlex/Javadoc with the new FlexDoc/Javadoc the same way as before. You should neither rename anything in your license file nor change the file name!
com.docflex.* moved to xyz.flexdoc.*
The possibility of designing tables in templates has been considerably extended.
Now, you can define dynamic tables of any complexity, with some cells spanning both several columns and several rows. (Before this version, only multi-column spanning cells were possible.)
That is supported both:
At that (as always), the tables defined in old templates will remain the same and work perfectly as well, with no need to change anything in them.
Four more types of template formatting styles have been supported:
Besides simplifying the programming of templates, template styles can be rendered into similar structures of particular output formats. For instance, in HTML output the template styles can be translated into named CSS rules, which allow you to substitute particular formatting properties using purely HTML/CSS means (e.g. custom CSS file). See also: HTML Output | Custom CSS Rules.
Before this version only two style types were supported:
Template Call is a template component that allows you to call one template from another. Here, the called template (or subtemplate) serves as a procedure. It may generate either a separate file or a piece of the file generated by the calling template. A Template Call has a lot of settings (among them, of course, passing template parameters).
Now, one more group of settings has been added – the list of style overrides.
Each template may define formatting styles. These are the named groups of formatting properties that can be assigned to a template component at once just by specifying the style name. The formatting styles are template local things. That is, they are not imported from somewhere outside. But when a template is called from another template, the styles defined in the calling template will override the equally named styles defined in the called template. When multiple templates are called one from another, that will work in a chain. So, the styles defined in the main template will override any equally named styles defined elsewhere. As a whole, formatting styles behave as additional template parameters passed implicitly by their names.
Now, it is possible also to specify explicitly for a given Template Call how the style overriding occurs. For each style found in the called template, a style override can be defined that tells exactly which style from the calling template will override it (regardless of the style name). That adds a lot more flexibility!Style overrides are specified in the Template Call property dialog on the "Call Settings | Style Overrides" tab.
Processing of a Template Call is rather time-consuming. The fewer of them are in a template the better they can be optimized. Moreover, templates cannot be called directly from FlexQuery expressions.
The solution is to use stock-sections as light-weight proxies of template calls (stock-sections can be called also from FlexQuery expressions). That is, a template call is defined only once within a stock-section, and then that stock-section is called from anywhere, instead of the template.
Previously, that was possible only by defining a Folder stock-section and the Template Call Section within it.
Now a Template Call Section itself can be specified as stock-section (which, of course, reduces all the processing).
A new text formatting property has been supported: character spacing (e.g. see: Text Control | Properties Dialog | Formatting | Text | Spacing | Character spacing).
It allows you to specify spacing between characters in length units. The main benefit of this property is a possibility to specify exact spacing between short pieces of text (which, for instance, may serve as items of a horizontal menu).
The formatting of lists has been enriched with two more properties:
| Property | Description |
|---|---|
| List | Bullet | Image File | Specify the bullet image file. This property allows you to replace the standard list bullet with a custom image. |
| List | Bullet | Image Output Directory Expression | Specify the FlexQuery expression that generates the pathname of the output folder where the bullet image file is to be stored (typically, it is with all other icons). |
For Image Control, it is possible now to specify paddings around the image. See: Image Control | Properties dialog | Formatting | Image tab.
The image paddings are supported in both HTML and RTF output formats. They may be particularly useful when inserting various icons in the documentation.
The early "Delimiter Control" has been renamed into "Separator Control" for better clarity.
Of course, any existing templates won't be spoiled by that!
A new template component has been added, which represents a page-break (e.g. see: Area Section | Local Menu | New Area Row | Page Break).
Previously, page-breaks could be specified only as formatting properties of template Sections, which made them difficult to control. A separate component gives a lot more flexibility (through the enabling condition) as well as visualizes page-breaks in Template Designer.
A new template section was introduced, whose job is only to execute the specified FlexQuery expression.
There is a demand for such sections within init.tpl template (in JavadocClassic template sets).
That template generates no output, but creates a number of element maps used across the entire template set.
That's done by executing lots of FlexQuery expressions specified in various template sections.
Previously, as a surrogate for Query Sections the Folder Section were used with the specified Init Expression.
That looked confusing and burdened processing.
A new functionality has been supported that makes possible to dynamically attach any data to particular DSM elements using special service attributes.
Service attributes serve the same role as normal element attributes. They allow you to attach specific data to particular DSM elements and access those data by names. However, unlike normal DSM attributes, service attributes are not provided by the DSM driver and not connected to the external data source. Rather, they are maintained by the generator itself in the form of a special hash-map.
That hash-map is actually very simple. Each service attribute is represented by a two-part key: { attrName; element.id }, where 'attrName' is the attribute name; 'element.id' is the unique identifier of the DSM element, to which the attribute is attached. Such a key is mapped to the attribute value.
The main purpose of service attributes is to use them as a data cache. That is to store some frequently needed information about particular elements, which although can be found in the Doclet DSM, practically is difficult to collect.To work with service attributes, the following FlexQuery functions have been added:
| Function | Description |
|---|---|
setServiceAttr() |
Assigns a service attribute with the specified name and value to the specified element. |
getServiceAttr() |
Returns the value of a service attribute with the specified name attached to the specified element. |
hasServiceAttr() |
Tests if there is a service attribute with the specified name attached to the specified element. |
removeServiceAttr() |
Deletes a service attribute with the specified name attached to the specified element. |
The full descriptions of those functions can be found in the Template Designer: Help | Assistant | Functions | By Category | Elements / Attributes | Service-Attributes.
The template file format has been made friendlier to view/edit template files manually (without Template Designer):
'\n' escapes).
'\uxxxx').
All changes of the template file format (above) are fully compatible with the old templates. So, any old templates will be equally read by the Template Designer or generator in this version. We always maintain backward compatibility of any templates (but not forward one)!
Now, you can search templates for a lot of various things:
| Search For | Search Results |
|---|---|
| Line number in template file | A template component, whose definition in the template file both contains this line and the smallest one. The purpose of this type of search is finding the template locations mentioned in the generator error diagnostics. |
| Parameter name | All template locations where there is access to a template parameter with that name (including the parameter definition). |
| Stock-section name | All template locations where a stock-section with that name is called (including its definition). |
| Style name | All template locations where a formatting style with that name is used (including its definition). |
| Unknown (lost) parameters | All template locations where there is access to template parameters, whose definitions are absent. |
| Unknown (lost) stock-sections | All template locations where there calls to stock-sections, whose definitions are absent. |
| All hypertext links and targets | All template locations where hypertext links/targets are defined. |
| All specified expressions | All template locations where there are specified FlexQuery expressions. |
The found template locations are shown in the form of tree (including all parent components), from where you can easily jump to the actual template components in Template Designer.
The search dialog is invoked from the Template Designer main menu > Edit > Find... item. Besides that, the same search can be run from the local menu for a selected template parameter, formatting style or stock-section at their definitions.
The editor of template parameter definitions (found in the Template Property Dialog | Parameter tab) has been completely reworked.
Previously, that was just the plain list with each line representing a parameter. As the number of parameters in some templates has grown to enormous quantity, that list eventually became practically unnavigable.
Now, the parameter definitions are represented in the form of tree with collapsible nodes (the same as in Parameter Inspector). Thereby, the usability of the parameter definition editor has been restored.
Expression Assistant provides a dynamic help system when writing FlexQuery-expression (those used to calculate various dynamic properties of template components and for other things).
As the number of FlexQuery-functions constantly increases (many actually overload the same functionality with different parameter signatures), the function tree in the Expression Assistant has been reorganized as follows:
Panel Control is a Control with a template area inside. That means it may contain other components (Area Rows and Controls) that define some complex content.
When a Panel Control defines a table cell, it should also somehow visualize the cell alignments. Previously, only horizontal alignment was shown on the level of Control Groups (which are the Area Rows containing Controls). Now, in addition to it, all Area Rows defined within the Panel Control are together aligned vertically as well. That depicts much better how the result table will look in the generated output.
The error diagnostics issued by the template interpreter has been completely reworked. Now, the full template location trace is reported with the corresponding line numbers in template files (similar to Java Stack Trace). Additionally, for some components, their context element is reported that shows which Doclet API object was being processed by the given template component at the moment of the error. For example:
-------------------------------------------------------------------------------- ERROR DETAIL -------------------------------------------------------------------------------- Generator Exception: No element map found with id 'excluded_members' -------------------------------------------------------------------------------- When executing function call 'checkElementsByKey' (expr: Ln 5, Col 3) -------------------------------------------------------------------------------- at Enabling Condition (class.tpl:6070) at Area Section (class.tpl:6068) at Folder Section for 'MethodDoc' (class.tpl:5752) at Stock-Section 'Operation' / Folder Section for 'ExecutableMemberDoc' (class.tpl:5681) with context element: MethodDoc {java.io.BufferedInputStream.read()} at Call Stock-Section 'Operation' (class.tpl:3653) at Element Iterator by '#CUSTOM | MethodDoc' (class.tpl:3600) at Folder Section (class.tpl:3386) at Folder Section (class.tpl:1391) at Template: C:\flexdoc-javadoc-1.7.0\templates\classic\lib\class.tpl with context element: ClassDoc {java.io.BufferedInputStream} at Call Template 'lib\class.tpl' (FramedDoc.tpl:914) at Element Iterator by 'ClassDoc' (FramedDoc.tpl:900) at Element Iterator by 'PackageDoc' (FramedDoc.tpl:840) at Template: C:\flexdoc-javadoc-1.7.0\templates\classic\FramedDoc.tpl with context element: RootDoc
Although templates are not supposed to be edited manually, you can use the template line numbers in Template Designer to find the corresponding template locations (see template search tools).
The -taglet and -tagletpath command-line options have been supported,
which allow you to specify respectively custom taglet classes and the search paths for taglet class files.
These options work the same as the -taglet and -tagletpath options supported by the Standard Doclet. For further details, please see Taglet Overview.
When FlexDoc Doclet finds a -taglet option
on the Javadoc command line, it loads the doclet class, initializes the doclet and puts it in a special internal hash-table
(according to tag name supported by the taglet).
The exact application of taglets is programmed in templates using a Javadoc-specific FlexQuery functions:
| Function | Description |
|---|---|
getTaglets() |
Returns all taglets specified with -taglet options on Javadoc command-line (that was possible to load and initialize).
|
getTaglet() |
Returns the Taglet registered to process tags with the specified name. |
callTaglet() |
Calls the specified Taglet to process a tag. |
The HTML generator has been almost entirely redeveloped to achieve the following goals:
Now, the HTML output can be generated in one of the markups:
The markup is selected with the option: Output | Markup
For those who wanted to customize the generated HTML documentation with their own CSS rules, it is possible now!
In case of HTML output, the CSS style sheet has been used before, but the CSS rules placed in it were effectively the sets of inline CSS properties generated by particular template components and collected together in a single style sheet to eliminate their repeating. The class selectors assigned to such CSS rules were completely unpredictable and could not be used to substitute the generated CSS rules with the custom ones. Such automatic CSS rules are generated now too and called anonymous CSS rules.
Starting from this version, a new type of CSS rules has been supported – named CSS rules. Those are generated from the formatting styles defined in templates. When such a style is assigned to a template component, each piece of HTML output (i.e. HTML element) produced by that component can be assigned with the CSS rules generated by that style. The class selector assigned to a named CSS rule is specified in the corresponding template style. So, the relation between a particular CSS class selector and the pieces of output where it is applied is predetermined. This makes possible to substitute the CSS rules (i.e. their properties) generated for those class selectors automatically, with the custom CSS rules provided by the user.
The difficulty of implementing of named CSS rules comes from the fact that several template styles can contribute to the result formatting of a particular template component. The styles can be either assigned directly to the component or inherited from its parents. Besides that, some formatting properties can be specified on the component directly without any styles at all. When that everything is rendered with a single anonymous CSS rule, only effective properties (left after all overriding) will get there. But when named CSS rules are used, they must replicate in CSS the same property overriding that occurs on the level of template styles. That wasn't simple to achieve!
For a lot more details please see: FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML.
Output | Markup
CSS
See also: FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML
CSS | Generate style sheet file
This option was actually present before, however not in this group.
CSS | Generate style sheet file | CSS pattern file
CSS | Generate style sheet file | Include anonymous rules
CSS | Generate named rules
Generation of named rules is essential for applying custom CSS rules
CSS | Generate named rules | Include descriptions
CSS | Generate named rules | Custom rule file
This setting is essential for applying custom CSS rules
CSS | Units
The possible are relative, pixel and point units.
Text | Render embedded HTML | Fix markup
This setting may be particularly important in case of XHTML output.
When a text (e.g. XML schema annotations) preformatted with HTML tags contains repeating whitespace (i.e. space and newline characters), those repeatings won't appear in the generated RTF output (the same it would be in case of HTML browsers).
That was not provided before this version.
A possibility has been supported to include a static Word document in the RTF document generated by FlexDoc.XYZ. That is done through a Data Control with the data source specified as "Document Field". A new "Include Text" field has been implemented. The included Word document file must be specified with the "Expression for Filename or URL", the parameter of that field.
Special efforts have been made to ensure that DocFlex/Javadoc works properly on macOS and can be immediately used there, namely:
.command files have been included to
It is the further development of the previous «JavadocPro» template set.
For more details, please see:
{flexdoc-javadoc}/templates/classic/README.html | Change Log
Now, all output documents (in HTML and RTF formats) generated under the general Trial License will be distorted by replacing some letters with bullet characters (as well as contain special messages).
It may sound odd. What images and hyperlinks can exist in plain-text files?
Yet, the plain-text output may be just a base layer for other file formats, for instance DITA, which is an XML-based markup. There, both images and hyperlinks do exist and are required.
The following new functionality will allow you to use plain-text output capability of DocFlex/Javadoc to generate some full-blown complex formats even when they are not supported by DocFlex/Javadoc directly.
Images
In plain-text mode, an Image Control will produce the same image file (according to its setting). However, in addition, it also emits into the main output the image file's relative pathname. That pathname is calculated against the main file's location and the name-separator is UNIX style ("/"). In a template, you can surround the Image Control with other Text Controls generating some markup, so everything would produce both the image file and the image tag for it in the main output.
Hyperlinks
Now, you can generate cross-hyperlinks in plain-text files too. This equally includes the hyperlinks from images (the imagemaps).
What a hyperlink actually is depends on the final format you generate using the plain-text output. DocFlex/Javadoc just provides the necessary functionality to find the things you want to link from and to. This is implemented in the form of new FlexQuery functions and GOM types ("GOM" stands for Generator Object Model):
| Function / Type | Description |
|---|---|
findHyperTarget() |
Finds a hypertarget matching the specified set of keys that may exist anywhere
in the whole generated documentation. Returns a GOMHyperTarget object
describing the target.
|
GOMHyperTarget |
Provides information about a hyperlink target. This includes the output file containing the target and the target name. |
More details you can find in the Template Designer | Help | Assistant:
"JavadocPro" is a new template set provided with DocFlex/Javadoc since the version 1.6.0. Using it you can generate:
This everything is complemented with a possibility to selectively filter classes and members by tags/annotations, a feature not seen in any other software known to us!
Procedure templates are a special kind of templates that generate no output. Rather, they have been used internally in big template applications to employ the data querying and processing capabilities of template components (such as Element Iterator) for some auxiliary tasks (e.g. creating of element maps).
Now, the role of procedure templates has been extended, so they can be used also to generate multi-file documentation with no particular root. The following functionality has been supported:
The "Label Control" has been renamed into "Text Control" and more functionality added.
The purpose of Text Control is to specify some static text in templates. Now, unlike the old Label Control, it shows the full multi-line text directly in the designer pane (with the support of scrolling). This may be particular helpful, when you want to specify in templates some multi-line descriptions.
A new property has been introduced for template sections: "Output Notification Expression" (found on the "Component | Options" tab of the section property dialog in the Template Designer).
When that expression is specified, it will be executed each time the section has produced a non-empty output (on the finishing of the section processing).
This makes possible, for instance, to program such things like tracking whether particular output sections have been generated early and, depending on it, to add some kind of separator (e.g. horizontal rule) before the output that follows them.
A new property has been introduced for Element Iterators: "Expression for Grouping Key" (found on the "Processing | Sorting/Grouping | Grouping" tab of the Element Iterator properties dialog in the Template Designer). It allows you to break the iterated elements into groups so as to iterate, first, by the groups and, then, by the elements within each group.
It works as follows.
After the initial elements have been collected, filtered and sorted, the result sequence of elements is broken into groups according to the grouping keys generated for each element by the FlexQuery specified in the "Expression for Grouping Key" of the Element Iterator.
Each continuous subsequence of elements with equal grouping keys produces a group. As a result, the sequence of elements prepared for iterations is converted into a sequence of element groups. The ordering of elements in each group remains the same as in the initial sequence.
Since groups are not elements, the Element Iterator cannot iterate by them directly.
So, it will iterate by the first elements taken from each group.
However, at that, on each iteration step, the Generator Object Model (GOM) property
iterator.groupElements, which is accessible in FlexQuery expressions,
is updated so as to provide the enumeration of all elements
in the given group.
This allows you to specify a nested Element Iterator that will iterate by the elements
in the group received from the iterator.groupElements property.
Although, dynamic HTML is not currently in the focus of DocFlex templates, the following setting has been supported: Template | Properties | Output File | HTML Head Expression.
It specifies an expression that may produce a string, which will be included in the header (between <head>...</head> tags) of an HTML file generated by the given template. In particular, this allows you to embed in the generated HTML file any custom JavaScript code (enclosed in <script>...</script> tags).
For instance, this may be used to reload the 'detail' frame
(of a frameset defined in index.html) with another HTML document passed
to index.html via a URL parameter (specified after '?' in the initial URL).
This is supported now in JavadocPro templates
Hyperlinks are generated according to special link/target definitions specified in template components (see component's Properties Dialog | Hypertext tab). Now, hyperlink definitions themselves look more like components. The following settings/features have been added:
Some hyperlink definitions may be so complicated that they are better to be explained.
The same as in template components, it allows switching context element used for calculations of other hyperlink's settings.
Specify one or several element types, which the context element must match. This is a kind of filter. If the context element does not match any of the specified types, the whole hyperlink definition will be skipped.
A hyperlink is created when the vector of keys generated by the Link Key Expressions matches a similar vector of keys associated with a certain target (generated by a different component).
Now, in addition to single vector of keys, it is possible to define matrix of alternative keys. The matrix columns become alternative key vectors. If one vector cannot be matched, another is tried.
This allows unifying in a single hyperlink definition what were previously several ones, which simplifies programming and improves performance of the template.
Image Control has been extended with two new properties that control where the image file is saved and under which name:
{doc-root}/resources
This is supported now in JavadocPro templates
Previously, all images were saved only in a local 'doc-files' subdirectory associated with the given document (which is now also the case when no separate image output directory specified).This feature is interesting mainly in the case of element images, which are certain graphical depictions (e.g. some diagrams) of the entities represented by the DSM elements. This is not yet supported in DocFlex/Javadoc. (For example, dynamically generated UML class/package diagrams would be such "element images").
FlexQuery expressions are small program blocks (called queries) with a Java-like syntax that are used in templates to calculate dynamic properties of template components and for other needs. Now, the capabilities of this language have been extended:
return <result_expr>
It allows you to stop the execution of the query at any point and return the query result,
which is calculated by the result_expr specified in the return statement.
The type of the returned result is checked to comply with the data type necessary for the given query. This is done yet during the parsing of the query (e.g. in Template Designer).
A FlexQuery expression may also contain subqueries, which are nested code blocks executed not directly, but rather passed as parameters to functions. A function may call such a subquery repeatedly to calculate certain things (e.g. to check a filter condition for the elements processed by the function).
A subquery may also contain return statements, which will affect only the execution of that subquery.
The result_expr specified in such a return statement will be also checked, however,
now only to comply with the data type necessary for the given subquery.
The Java-style typecast operator has been supported:
(type) obj
where type may be any primitive type (like String or Number)
or GOM-type ("GOM" stands for Generator Object Model).
It allows you to quickly access properties of various GOM objects, provided via untyped references (mostly returned by various functions). Now, you can write something like this:
((GOMElement) getParam("name")).id
Previously, only special type-conversion functions (like toString() or toElement())
were available for such operations.
Casting to array types is also supported. You can write:
(type[]) obj
At that, the necessary conversion will be done even when the initially obj is an array
of a more generic type, however, containing only elements of the required type. For example:
objects = Array (1, 2, 3); // create an Object[] array with only integer elements ints = (int[]) objects; // convert it to an array of integers ints[0] * ints[1] * ints[2] // access array elements as integers
Embedded HTML is the HTML markup (tags) inserted by the user directly in various descriptions, annotations etc. (stored as plain text in XML files) in order to format them. To have that formatting show up in the generated documentation, in general, the embedded HTML markup needs to be processed (rendered) specifically, which depends on the output format. This is controlled by the "Render embedded HTML" option of the given output format.
Sometimes it is needed to remove all block-level HTML tags but leave any other tags, so that the result text would be displayed formatted but without any structure, as a single line. That, we call flattening.
It is supported now!
A new formatting property has been introduced for all template components: "Embedded HTML | Flatten" (found on the "Formatting | Text Flow" tab of the component properties dialog in the Template Designer). If it is selected, any embedded HTML markup found in the text output produced by the component will be flattened (given that the embedded HTML is processed both as a whole and for that component in particular). This will also affect all nested components (including called stock-sections), unless rendering of embedded HTML is specifically disabled in some of them.
Now, in the Parameter Inspector, those parameters that are irrelevant to the current settings (specified in other parameters) can be shown disabled. This will help navigating the parameter tree.
That is achieved by introducing new properties in the template parameter definition: "Enabling Condition" and "Group | Enabling Condition". They specify the boolean FlexQuery expressions (queries) that are evaluated each time any of the template parameters is changed:
It is possible now to map some of the non-core Javadoc command line options to the default values of template parameters.
Three new FlexQuery functions have been added for this:
hasOption(), getOption(), getOptions()
They can be used within the default value expression of template parameters, to calculate parameter values from particular option arguments.
That was needed, first of all, to fix the integration with the new versions of Maven and is supported now in JavadocPro templates.
Before this version, all descriptions of templates and their parameters could be stored only directly within the templates themselves. Now, they can be held also in separate text files located near the main templates. (The description text may also include HTML markup.)
This makes possible:
That functionality is achieved by introducing of a new macro:
${include <url>}
Such macros can be inserted both within the descriptions stored directly in templates and within the included text files themselves.
The url specified in the macro points to the file to be included.
The macro is expanded with the content of that file (after the expansion of any include
macros found in that file).
The file URL may be both absolute and relative one. If the macro is found within a description stored in a template, the relative URL is interpreted against the location of that template. If the macro is found within a text file, the URL is interpreted against the location of that file.
This everything has been applied in JavadocPro templates
All internal CSS declarations, which were previously defined and used only locally in every generated HTML document,
now can be held in a single 'stylesheet.css' file stored in the documentation root.
Only links to this file will be included in the generated HTML documents.
Although such CSS declarations look typlically rather gibberish, they tend to repeat across HTML files. So, moving them to a single CSS file may substantially reduce the overall size of the generated HTML documentation.
That possibility is controlled by a new "Output | Generate style sheet file" option.
What's more, using the nested "CSS pattern file" option, you can frame the generated CSS declarations into your own CSS file. That will allow you to include in the result CSS file your custom styles, which you can use to format the HTML markup embedded in your descriptions/annotations.
Output | Add Charset
When you frequently upload the generated docs into some repository, which stores only changes of files against their previous versions and your docs actually do not change, this will relieve the repository from unnecessary updates.
Output | Generate style sheet file | CSS pattern file
Thanks to all recent innovations, including storage of all internal CSS declarations in a single CSS file (see Generation of CSS file) and many others, the HTML generator works now on average 5% faster and generate output 15% smaller against the previous version 1.5.6.
The primary focus of the generated RTF was always MS Word. However, since 1.5.6, following some user complaints, we uncovered and fixed a lot of problems of compatibility with other RTF readers. For instance, under WordPad, certain features of the old RTF output might be distorted, or the whole doc might get invisible starting from some point.
RTF is poorly documented format ridden with various legacy contradictions. So, it is not very simple to get all known RTF reader work correctly together, particularly, when you have a rather complex RTF.
Now we've fixed a lot of such issues. So, the generated RTF seems to work OK with all RTF reader we tried:
Before this version, all formatting styles defined across a template set, which are not overridden by other equally named styles from parent (calling) templates, would produce the same number of separate styles in the RTF.
Now, this is changed:
That optimization prevents the contamination of the generated RTF with many unused styles (which have been defined in templates but never used) and duplicated styles (which are defined in several subtemplates, but never in the main one).
The automatic wrapping of very long nonbreaking strings within table cells has been reworked once again.
The problem is that MS Word cannot wrap such strings by itself, which causes the table to stretch beyond the visible page.
The previous algorithm worked well when such strings appeared only in one table column. But when they happened to be in several columns, the algorithm failed and the table was laid out by Word again beyond the page width.To deal with that problem, the following things have been implemented:
then a property similar to "Tables | Break long nonbreaking strings | Maximal unbroken width" option can be specified for each table cell/column; see:
The src attribute now can specify not only a formal URL but also a local file pathname
(e.g. c:\element.gif). Such an image will be shown in RTF.
Also, when the image file specified in src attribute cannot be found and
the "Images | Show failed image path" RTF option selected,
the failed image's pathname (or URL) will be shown in the generated RTF (along with a placeholder).
Previously, all <img> tags with failed images were just ignored.
That has been completely reworked.
Previously, when "Text | Render line breaks" RTF option was selected and some embedded HTML happened to contain table tags (<table>,<tr>,<td>) intermitting with newlines, the rendering of such a markup in RTF could produce tables with extra cells. Now, this is fixed!
Before this version, when some HTML formatting was specified within a table cell, like:
<table><tr><td><font color="red">blah-blah-blah</font></td></tr></table>
it didn't work ('blah-blah-blah' wouldn't be red). Now, this is fixed!
Hypertext | Generate hyperlinks
Note: To have cross-reference hyperlinks (those pointing within the same document) be generated, the "Hypertext | Generate bookmarks" option must also be selected. Without it, only external (URL) hyperlinks will be possible.
Bookmarks are needed to generated both cross-reference hyperlinks and page number references.
Hypertext | Bookmark name prefix
This option may be useful when you need to merge several RTF files produced with DocFlex into a single document. In that case, you should generate those files with different bookmark prefixes. This will ensure that the bookmarks from different RTFs never overlap and all hyperlinks and page number references in the result document are correct.
Tables | Break long nonbreaking strings | Maximal unbroken length
This option lets you define what a long nonbreaking string actually is (thereby preventing breaking of some resonably long words and names).
Tables | Break long nonbreaking strings | Maximal unbroken width
For all details, see the description of this option in: Generator GUI | Output format | RTF | Options | "RTF Option" dialog
Tables | Break long nonbreaking strings | Use optional breaks
Other | Suppress Timestamp
In the case when the DocFlex Doclet is run with the enabled GUI, the generator dialog has been re-implemented using JFrame so that it is visible on the Windows taskbar as a Swing application.
The integration with Apache Maven 2.2.x - 3.0.x has been specifically worked out.
Although, Maven Javadoc Plugin
is supposed to work with any Javadoc doclets, since Maven 2.2.x it always emits various
Standard Doclet options
(like -author, -bottom etc.), which break execution of any custom doclet,
unless it supports them too.
Javadoc itself requires for a doclet to recognize all non-core options. The Standard Doclet options are non-core. So, when found on the Javadoc command line, they break the execution of the doclet unless it supports them. Supporting of an option means not only returning OK for it, but also how many arguments it has.
So, we needed to develop the whole mechanism of mapping options to template parameters to work around all this.
Since this version, DocFlex/Javadoc supports multi-valued template parameters (called also list parameters, for short).
Such parameters allow you to pass into template the whole vector of different values
associated with the same parameter name. This provides a universal mechanism for implementing
a user control over how a set of templates processes a certain type of data (or situations)
that may come in unlimited number of variations.
A list parameter can be specified both in the Parameter Inspector dialog of the doclet GUI
and on Javadoc command (using one or many -P options).
List parameters have been immediately used in standard templates to re-implement all "Exclude By Tags" and "Exclude By Annotations" parameters and to support a new functionality of "Include Custom Tags" parameter (see below).
Most of the data processed by templates come from some external data source (e.g. Doclet API) via its virtual XML-like representation called Data Source Model (DSM), which maps everything onto some elements and their attributes. Therefore, most of the functionality available in templates (such as iterators, hash-maps and so on) is about elements and attributes.
But what if you want to use that functionality to process some different kind of data, for instance, those coming from template parameters or elsewhere?
Now, you can do that using custom elements!
For more details, please see Template Designer | Help | Assistant:
We have used this new functionality immediately to implement the processing of "Include Custom Tags" parameter (see below).
Doclet API Data Source Model (or Doclet DSM, for short) is a virtual XML-like representation of the entire Javadoc Doclet API in the form of a tree of elements and attributes. All DocFlex templates are based on that representation. DSM Type is a particular mapping of the Doclet API classes and methods on the DSM elements and attributes.
Since now, DocFlex/Javadoc uses a new version of such a mapping. It is different from the old one just in a few places.
The reason why the new mapping (DSM Type) was needed is the support of the notion of
parent element: a new GOMElement.parent property and findAncestor()
function have been introduced. (Later, there will be also a special Location Path axis 'parent'.)
The notion of parent element is opposite to the notion of child element.
If element1 is a child of element2, then element2 must be the parent
of element1. In particular that means, given
element1 = element2.findChild ("SomeElementType");
the following must be true:
element1.parent.id == element2.id
That is not always true (in all situations) for the old mapping. The new DSM Type fixes it.
The standard templates have been switched to the new mapping. The old mapping is supported as well, for compatibility with any previous custom templates.
Thanks to some new optimizations, all output generators work 15-20% faster now.
The following is the result of the generation of framed HTML documentation
by all Java sources of java.*, javax.*, org.* packages
(including all their subpackages), which constitute the entire
Java SE 6 API Specification
currently provided by Sun:
| Number of Java classes: | 3821 |
| Total source code size: | 40.4 Mb (all files) |
| Generation time: | 323 sec |
| Result HTML documentation: | 39.7 Mb |
| Number of generated files: | 4216 |
| Computer platform: | Intel Core 2 Duo E6600 based system / Windows XP |
| JDK version: | 1.6.0_10 |
For comparison, the same test run with the previous v1.5.5 took 393 sec.
The automatic wrapping of very long nonbreaking strings within table cells has been improved.
Until this version, such a wrapping was done correctly when the string was generated by the same control. When the entire nonbreaking string was produced by different controls (possibly using different fonts), it was not recognized as a single string and, therefore, was not broken as needed. That caused some summary tables in RTF JavaDoc to expand beyond the page width.
Now, this is fixed!
For more details about that problem with long nonbreaking strings in RTF, see Doclet GUI | RTF Options | Tables | Long string wrapping factor.
The "Include | Tags | Custom Tags" (include.tag.custom) parameter,
which was present in the standard templates previously, has been completely redefined to support a functionality
similar to that of
-tag
option provided by the
Standard Doclet.
In particular, using this parameter, now you can selectively include in the generated output the documentation of your custom tags, specify the tag headings as well as their ordering. You will be able also to redefine the headings and ordering of the standard tags (such as @param, @see, @author etc).
All that new sophisticated functionality of this parameter has been implemented entirely in standard templates using new general features Multivalued (List) Parameters and Custom Elements introduced in this version.
Processing/documenting of tags has been completely reworked.
The old tags.tpl subtemplate has been eliminated.
Now, all tags are processed in "tag documentation" sections of the template blocks that generate the details for each type of Java language constructs (package, class, constructor, method, field).
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"
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.
"break when section produced 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 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.
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 "javadoc" 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):
| 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 |
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:
| 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 |
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.