Chapter 7
Generating Documentation

The ech2doc and ech2javadoc translators are used to support the generation of browsable ECharts machine code documentation. The output from both translators includes interactive SVG ECharts machine diagrams. As such, both translators rely on ech2dot and dot, the programs used to generate ECharts machine diagrams described in Section  6.

7.1 Interacting with Diagrams

There are a number of ways that a user may interact with the ECharts SVG diagrams included in the generated documentation. Viewing and interacting with an SVG diagram requires that a web browser be configured with an SVG viewer plugin. See Section  7.4 for more information.

1. Highlight transitions and states by rolling the cursor over them.
2. Display user comments for a machine, its transitions and its states by resting the cursor over the respective machine element.
3. Clicking on a state with a nested submachine navigates the browser to the diagram of the submachine nested in the state.
4. Pan a diagram that may be too large to fit in the viewing window. For Internet Explorer, hold the ‘alt’ key while dragging the diagram. For Safari, hold the ‘shift’ key while dragging. For Firefox, click on the ‘pan’ tool icon and then hold the ‘shift’ key while dragging.
5. Zoom in and out of a diagram. For Internet Explorer, hold the ‘control’ key and click to zoom in at the mouse pointer location. Hold the ‘control’ key and click-and-drag to select a region to zoom into. Hold the ‘control’ and ‘shift’ keys and click to zoom out. You can also use the zoom commands in the context menu. For Safari, use the ‘View -¿ Make Text Bigger’/‘View -¿ Make Text Smaller’ menu options or use the keyboard shortcuts ‘command +’/ ‘command -’. For Firefox, select the ’zoom’ tool icon and scroll your mousewheel or press the ‘+’/‘-’ keys.

7.2 ech2doc

The ech2doc translator generates a web site whose pages provide a host-language independent overview of ECharts machine code. This program’s output and options are similar to those provided by Java’s javadoc tool. The ech2doc translator only generates documentation for ECharts .ech files and not for any supplemental host language files that may exist. Furthermore, pages generated by the ech2doc translator only include user comments for the machine, its constructors, its states and its transitions. The pages do not include user comments for host language constructs such as field or method declarations.

Here’s an example of using the ech2doc translator for the examples machine package included with the ECharts SDK. In this example we assume the working directory to be runtime/java/src/examples of the ECharts SDK. We also adopt the following Unix conventions: the command line prompt is a percent character %, long commands are split over multiple lines using the backslash character \ at the end of a line, and the command line continuation prompt for a command split over multiple lines is the ‘greater than’ character >.

Running this command creates a web site in the directory /tmp/ech2doctest with the front page (/tmp/ech2doctest/index.html) shown in Figure  7.1. Clicking on the Example0001 link in the All Machines frame displays the page shown in Figure  7.2.

Figure 7.1: ech2doc front page

Figure 7.2: ech2doc Example0001 page

The ech2doc translator supports many of the same command line options as Java’s javadoc tool. These options are discussed in the ech2doc command reference in Section  8.

7.3 ech2javadoc

Unlike the ech2doc translator discussed in Section  7.2 which is a host language independent documentation generator, the ech2javadoc generator discussed in this section is intended for ECharts machines translated to Java using ech2java. The standard program for documenting Java classes and packages is javadoc¹. The ECharts SDK provides two utilities that enhance javadoc for documenting Java source code that includes ECharts machines: (1) the ech2javadoc translator which generates interactive SVG diagrams for ECharts machines and (2) the javadocpp program which post-processes ECharts machine class documentation produced by javadoc in order to incorporate machine diagrams into the documentation.

Here are the commands required to generate javadoc documentation for the examples package included with the ECharts SDK. We assume the working directory to be runtime/java/src/examples of the ECharts SDK.

The first command (ech2javadoc) translates the ECharts machines in the examples package into SVG diagrams and places them in the docfiles subdirectory of the examples directory in which the machines are located. The ech2javadoc command also creates an auxiliary .html file for each SVG diagram and places these files in the same docfiles subdirectory. Running the second command (ech2java) is only required if ECharts machines haven’t yet been translated to Java. The ECharts machines must be translated to Java in order to be referenced by javadoc. The third command (javadoc) generates documentation for the Java files in the examples package and places it in the /tmp/ech2javadoctest directory. The fourth command, javadocpp, post-processes the documentation generated by javadoc to customize the documentation for ECharts machines (see Section  8 and Appendix  A for information on running this command and the ECharts translator commands). In particular, javadocpp removes documentation for any constructors, methods or fields that may be introduced by the ech2java translator but are not explicitly declared in a machine by the programmer. The program also adds a button onto documentation pages for machines. As an example, Figure  7.3 shows the page generated for the Example0001 machine. Note the button labeled Machine. Clicking on this button opens a new window displaying the machine’s interactive SVG diagram as shown in Figure  7.4.

Figure 7.3: ech2javadoc Example0001 page

Figure 7.4: ech2javadoc Example0001 diagram

The ech2javadoc translator supports a number of command line options for customizing its behavior. These are enumerated in the ech2javadoc command reference in Section  8.

7.4 SVG Viewers

Viewing and interacting with SVG machine diagrams embedded in ECharts documentation web pages requires a web browser with SVG support. Both Safari version 3.x (for Mac OS X and Windows) and Firefox version 2.x (for Mac OS X, Linux and Windows) provide native SVG support. Firefox users should download the “SVG Zoom and Pan” Firefox extension² which provides pan/zoom support. For Microsoft Internet Explorer we recommend using Adobe’s SVG viewer browser plug-in version 3.x³.