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.
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.
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.
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.
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 javadoc1. 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.
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.
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 extension2 which provides pan/zoom support. For Microsoft Internet Explorer we recommend using Adobe’s SVG viewer browser plug-in version 3.x3.