Now, all output documents (in HTML and RTF formats) generated under the general Trial License will be heavily distorted by replacing some letters with bullet characters (as well as contain special messages).
This should help some our users to respect the trial license terms.
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/XML to generate some full-blown complex formats even when they are not supported by DocFlex/XML 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/XML 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:
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
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
toString() or toElement())
were available for such operations.
Casting to array types is also supported. You can write:
(type[]) obj
obj is an array
of a more generic type, however, containing only elements of the required type. For example:
(In the case, when the initial array contains object of incompatible types, an error will be reported.)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.
Specifies the encoding of the generated HTML files.Output | Add Charset
Specifies whether to insert the character encoding declaration in the generated HTML files. The encoding name will be taken from the "Character Encoding" option.Output | Suppress Timestamp
Specifies whether to suppress the date/time information included in a special comment inserted automatically at the beginning of every generated HTML file.Output | Generate style sheet fileWhen 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.
Specify whether to generate a separate style sheet file containing most of internal CSS declarations generated by DocFlex (instead of holding them in every HTML documents where they are used).Output | Generate style sheet file | CSS pattern file
Allows you to frame the CSS declarations generated by DocFlex into your own CSS 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. |
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. |
To deal with that problem, the following things have been implemented:
(e.g. see: Template Designer | Section's Properties Dialog | Formatting | General | Section Output | "Table")then a property similar to "Tables | Break long nonbreaking strings | Maximal unbroken width" option can be specified for each table cell/column; see:
Template Designer | Control's Properties Dialog | Formatting | Table Cell | Options | Max width allowed for long nonbreaking strings
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
Specify whether to add hyperlinks in the RTF output.Hypertext | Generate bookmarksNote: 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.
Specify whether to add bookmarks in the RTF output.Hypertext | Bookmark name prefixBookmarks are needed to generated both cross-reference hyperlinks and page number references.
Specify prefix for automatically generated bookmark names.Tables | Break long nonbreaking stringsThis 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.
Specify whether to break automatically the long nonbreaking strings placed within the tables with the 'table autofit' setting.Tables | Break long nonbreaking strings | Maximal unbroken length
Specify the maximal characters length for a nonbreaking string (i.e. non-wrapping text) allowed to be left unbroken.Tables | Break long nonbreaking strings | Maximal unbroken widthThis option lets you define what a long nonbreaking string actually is (thereby preventing breaking of some resonably long words and names).
Specify the maximal width for a long nonbreaking string (i.e. non-wrapping text) allowed to be left unbroken. Precisely, it is the percent of the table width, in which any nonbreaking string should be wrapped.Tables | Break long nonbreaking strings | Use optional breaksFor all details, see the description of this option in: Generator GUI | Output format | RTF | Options | "RTF Option" dialog
Specify whether to use 'Non-width Optional Breaks' when breaking long strings for wrapping.Other | Suppress Timestamp
The same as HTML option: "Output | 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:
|
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"
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 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):
|
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.