# DocFlex/Javadoc - Change Log

## Table Of Contents

- Version 1.6.0

  - New "JavadocPro" Template Set
  - Template language / general functionality
    - Procedure Templates
    - Text Control
    - Section Flow Control
    - Grouping of elements with Element Iterators
    - Adding JavaScript in generated HTML
    - Definition of hyperlinks
    - Output directory/file for Image Control
    - New capabilities of FlexQuery expression language
    - Flattening of embedded HTML
    - Disabling of irrelevant parameters
    - Mapping Javadoc options to template parameters
    - Separation of template/parameter descriptions from templates
  - HTML Output
    - Generation of CSS file
    - New HTML Options
    - Performance improvement
  - RTF Output
    - Compatibility with other RTF readers
    - Optimization of RTF styles
    - Wrapping of long non-breaking strings in tables
    - Rendering of embedded HTML
    - Size and scaling of EMF Images
    - New RTF Options
  - Doclet GUI
  - Maven Integration

- Version 1.5.6

  - Template language / general functionality
    - Multivalued (List) Parameters
    - Custom Elements
    - Doclet DSM Type, Version 2
  - Template interpreter / output generator
    - Performance improvement
    - Very long nonbreaking string in RTF
  - Standard Templates
    - Documenting of custom tags
    - Changes in Standard Template Set

- Version 1.5.5

  - Template language / Template Designer
  - Template Designer / Doclet GUI
  - Output Generators
  - Maven Example

- Version 1.5.4

  - New licensing system
  - Generator GUI | Template Parameter Inspector
  - Template Designer
  - Template interpreter / output generator
  - Standard Templates

- Version 1.5.3

  - Generator GUI | Template Parameter Inspector
  - Template Designer

- Version 1.5.2

  - Standard Templates
    - New template parameters
    - Template set for Java 1.4
  - Template Language
  - Template Designer

- Version 1.5.1

  - Standard Templates | New template parameters
  - Template Language
  - Template interpreter / output generator

- Version 1.5.0

  - Full support of Java 5 language features
  - Performance improvement

- Version 1.4.11

  - Template interpreter / output generator
  - Template Language / Generator Object Model (GOM)

- Version 1.4.10

  - Template interpreter / output generator
  - Generator Object Model (GOM)

- Version 1.4

  - DocFlex/Javadoc now supports Linux
  - New RTF option
  - Improved support for external document viewers

- Version 1.3

  - Performance improvement
  - Standard Templates | New template parameter
  - More command line option support
  - New HTML option

- Version 1.2

  - Full support of table tags in embedded HTML
  - Standard Templates | New template parameters

- Version 1.1

  - Upgrade with the latest DocFlex core
  - Lots of new documentation on the DocFlex Technology
  - Improvements in templates

- Version 1.0

## Version 1.6.0

- New "JavadocPro" Template Set

  "JavadocPro" is a new template set provided with DocFlex/Javadoc since the version 1.6.0. Using it you can generate:

  - Framed HTML JavaDoc identical to the classic one.
  - Single-file HTML JavaDoc with basic content (project overview, package summaries, class details)
  - The newly redesigned RTF JavaDoc (which can be further converted to PDF).
  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!

- Template language / general functionality

  - Procedure Templates

    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:

    - A procedure template can be specified directly to the generator, that is, used as a main template.
    - Procedure templates can call from themselves other templates, including document and frameset templates, which would generate separate documentation files.
    - A procedure template may include definitions of any number of parameters (with any complexity) to control a large template application, as well as all the formatting styles to be inherited by the called subtemplates.

  - Text Control

    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.

  - Section Flow Control

    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.

  - Grouping of elements with Element Iterators

    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.

  - Adding JavaScript in generated HTML

    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

  - Definition of hyperlinks

    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:

    - Description

      Some hyperlink definitions may be so complicated that they are better to be explained.

    - Expression for New Context Element

      The same as in template components, it allows switching context element used for calculations of other hyperlink's settings.

    - Matching Element Type(s)

      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.

    - Matrix of alternative keys

      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.

  - Output directory/file for Image Control

    Image Control has been extended with two new properties that control where the image file is saved and under which name:

    - "Expression for Image Output Directory" provides the pathname of the directory where the images produced by the given Image Control is be stored. In particular, this allows saving all standard documentation icons in a single directory (and, therefore, to prevent duplicating them):

      > `{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).

    - "Expression for Image File Name" provides the name of the output image file.

      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").

  - New capabilities of FlexQuery expression language

    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' statement

      > `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.

    - Typecast operator

      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

      (In the case, when the initial array contains object of incompatible types, an error will be reported.)

  - Flattening of embedded HTML

    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.

  - Disabling of irrelevant parameters

    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:

    - When the "Enabling Condition" query returns false, the given parameter is disabled.
    - When "Group | Enabling Condition" query returns false, all parameters in the group headed by the given parameter are disabled.

  - Mapping Javadoc options to template parameters

    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.

  - Separation of template/parameter descriptions from 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:

    - To reuse the same descriptions in several main templates
    - To reduce the sizes of main templates considerably thereby making them loadable faster

    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

- HTML Output

  - Generation of CSS file

    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.

  - New HTML Options

    Output | Character Encoding

    > 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.

    > 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

    > 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.

  - Performance improvement

    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.

- RTF Output

  - Compatibility with other RTF readers

    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:

    - MS Word 2000, 2007, 2010
    - WordPad under Windows XP, Vista, 7
    - LibreOffice (Windows/Linux)

  - Optimization of RTF styles

    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:

    - An RTF style is generated only when it is actually used (that is, there are references to it).

    - All equally named styles (defined in a template set), whose all properties are equal and which are not overridden by other styles from calling templates, will produce the only style in RTF (with those name and properties).

    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).

  - Wrapping of long non-breaking strings in tables

    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:

    - When the table is generated by a template component

      > (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

    - When the table is generated by some embedded HTML markup (i.e. <table>,<tr>,<td> tags), the above setting is estimated dynamically according to the overall content of each table column.

  - Rendering of embedded HTML

    - <img> tags

      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.

    - Rendering of line breaks (newlines)

      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!

    - Formatting within table cells

      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!

  - New RTF Options

    Hypertext | Generate hyperlinks

    > Specify whether to add hyperlinks in the RTF output.

    > 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.

    Hypertext | Generate bookmarks

    > Specify whether to add bookmarks in the RTF output.

    > Bookmarks are needed to generated both cross-reference hyperlinks and page number references.

    Hypertext | Bookmark name prefix

    > Specify prefix for automatically generated bookmark names.

    > 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

    > 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.

    > 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

    > 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.

    > 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

    > 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"

- Doclet GUI

  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.

- Maven Integration

  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, 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.

## Version 1.5.6

- Template language / general functionality

  - Multivalued (List) Parameters

    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).

  - Custom Elements

    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:

    - Function By Category | Elements / Attributes | Custom Elements
    - All Element Types | #CUSTOM

    We have used this new functionality immediately to implement the processing of "Include Custom Tags" parameter (see below).

  - Doclet DSM Type, Version 2

    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.

- Template interpreter / output generator

  - Performance improvement

    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.

  - Very long nonbreaking string in RTF

    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.

- Standard Templates

  - Documenting of custom tags

    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.

  - Changes in Standard Template Set

    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).

## Version 1.5.5

- Template language / Template Designer

  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.

  > 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"

  > 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.

- Template Designer / Doclet GUI

  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!

- Output Generators

  The EMF image format has been supported. Now, the EMF images can be inserted both in the generated HTML and RTF documents. All supported (and tested) image formats now include: GIF, PNG, JPG, WMF, EMF, BMP.

- Maven Example

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

## Version 1.5.4

- New licensing system

  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.

- Generator GUI | Template Parameter Inspector

  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).

- Template Designer

  - The improved support of the definition of template parameters (see above).

  - Support of Copy/Paste of all settings at once specified in a particular tab (e.g. "Processing") of a component property dialog, including all sub-tabs.

    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).

- Template interpreter / output generator

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

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

- Standard Templates

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

## Version 1.5.3

- Generator GUI | Template Parameter Inspector

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

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

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

- 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!

## Version 1.5.2

- Standard Templates

  - New template parameters

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

    1. Exclude By Annotations | classes & members

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

    2. Exclude By Annotations | classes

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

    3. Exclude By Annotations | members

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

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

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

  - Template set for Java 1.4

    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.

- Template Language

  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().

- Template Designer

  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.

## Version 1.5.1

- Standard Templates | New template parameters

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

  1. Exclude By Tags | classes & members

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

  2. Exclude By Tags | classes

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

     The effect will be that each visible inheritable member of the excluded class will appear in every direct descendant of that class being documented (as if that member was defined directly there). This may be especially helpful when you will need next time to change your implementation while keeping intact what you have declared in your open API.

  3. Exclude By Tags | members

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

- Template Language

  - A new function `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().

- Template interpreter / output generator

  - Reworked scaling of images in HTML.

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

    Now, when generating HTML, the DocFlex generator itself converts point size into pixel size according to the DPI value specified in the formatting properties of the given templates (see: Template Designer | File | Properties | Formatting | General | Resolution (DPI)). So, in HTML, the new image size will always be specified in pixels.

  - Support of images in BMP format.

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

## Version 1.5.0

- Full support of Java 5 language features

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

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

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

- Performance improvement

  The following are two tests that have been run on Java SE 6 JDK Source Code (downloaded from: http://download.java.net/jdk6/) using 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

## Version 1.4.11

- Template interpreter / output generator

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

- Template Language / Generator Object Model (GOM)

  - Init/Finish Expressions are now supported in Area Sections.

  - The font size assigned to a particular template component can be specified now not only as a fixed value but also relatively (in percents) to the font size of the component's context. (See component's Properties Dialog | Formatting | Text tab).

  - The "Alignment" formatting property of Image Control has been extended up to five possible setting:

    1. Bottom (base line)
    2. Middle (base line)
    3. Top (text line)
    4. Left (margin)
    5. Right (margin)

    (See Image Control Properties Dialog | Formatting | Image tab).

  - A new GOM property `OutputFormat.renderEmbeddedHTML` has been added to indicate if "Render embedded HTML" format option has been specified for the generator.

## Version 1.4.10

- Template interpreter / output generator

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

- Generator Object Model (GOM)

  - New properties `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.

## Version 1.4

- DocFlex/Javadoc now supports Linux

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

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

- New RTF option

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

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

- Improved support for external document viewers

  The "openURL" setting, which is contained in `docflex.config` (the main DocFlex configuration file located in `lib` directory near `docflex-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.

## Version 1.3

- Performance improvement

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

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

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

- Standard Templates | New template parameter

  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.

- More command line option support

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

    For example:
      `-launchviewer`
        Do launch viewer
      `-launchviewer=false`
        Do not launch viewer, no matter what's specified in the `generator.config`

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

- New HTML option

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

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

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

## Version 1.2

- Full support of table tags in embedded HTML

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

  Now, almost all HTML tags (and their attributes) practically usable in doc-comments are supported. Here's the list of all supported HTML tags:

  Text | <b>, <strong>, <i>, <em>, <code>, <tt>, <u>, <s>, <strike>, <sub>, <sup>, <font>, <br>
  Paragraphs | <p>, <center>, <div>, <pre>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <blockquote>
  Lists | <ul>, <ol>, <li>, <dl>, <dt>, <dd>
  Table | <table>, <tr>, <td>, <th>
  Other | <hr>, <img>, <a>...</a>

- Standard Templates | New template parameters

  New template parameters have been introduced for better control of the content and formatting of the printable documentation generated by `PlainDoc.tpl` standard template:

  - Include/exclude details of inner classes
    Controls whether inner classes should be included into the generation scope.

  - Include initial values of fields
    Specify whether the initial values of fields should be shown in the documentation.

  - Omit inherited member lists for packages
    Suppresses generation of lists of the inner classes, fields or methods inherited from those classes/interfaces, which belong to the packages specified with this parameter.

  - Omit all inherited member lists
    Suppresses generation of all inherited member lists.

  - Start package from new page
    Forces each package documentation to start from a new page.

  - Start class from new page
    Forces each class documentation to start from a new page.

## Version 1.1

- Upgrade with the latest DocFlex core

  - Lots of old bugs fixed
  - Performance of the generator improved -- some tests show the generator is working now about 15% faster.
- Lots of new documentation on the DocFlex Technology

  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.

- Improvements in templates

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

## Version 1.0

  The story starts here!

Copyright© 2004-2012 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.
To contact us, please visit www.filigris.com or e-mail to: contact@filigris.com