javafxdoc - JavaFX documentation utility

NAME

javafxdoc - JavaFX Documentation Utility. This tool extracts formatted comments embedded in JavaFX source code files and organizes and displays those comments in HTML format.

Synopsis

javafxdoc [Options] [packagenames] [sourcefilenames] [ -subpackages] pkg1:pkg2:... [@argfiles]

Arguments can be in any order. See Processing Links for details explaining how the javafxdoc tool determines which source code files to process.

Options

Command line options, as specified in this document.

packagenames

A series of names of packages, separated by spaces, such as javafx.lang javafx.xml or javafx.gui.effect. You must separately specify each package that you want to document. Wildcards are not allowed. Use -subpackages for recursion. The javafxdoc tool uses sourcepath to look for these package names.

sourcefilenames

A series of source file names, separated by spaces, each of which can begin with a path and contain a wildcard such as asterisk (*). The javafxdoc tool processes every file name ending with ".fx", where the file name stripped of that suffix, is a legal module name (see Identifiers). Therefore, you can name files with dashes (such as X-Buffer), or other illegal characters in order to prevent them from being documented. The path that precedes the source file name determines where javafxdoc will look for the file. (The javafxdoc tool does not use sourcepath to look for these source file names.) Relative paths are relative to the current directory, so passing in Button.fx is identical to ./Button.fx. For example, a source file name with an absolute path and a wildcard is /home/src/java/awt/Graphics*.fx.

subpackages

Generates documentation from source files in the specified packages and recursively in their subpackages. An alternative to supplying package names or source file names.

Command-line Argument Files

A command line argument file contains a list of javafxdoc options, packagenames and sourcefilenames in any order. Wildcards (*) and -J options are not allowed in these files.

To shorten or simplify the javafxdoc command line, you can specify one or more files that themselves contain arguments to the javafxdoc command (except -J options). This enables you to create javafxdoc commands of any length on Microsoft Windows and or Macintosh OS X.

javafxdoc Options

Description

The javafxdoc tool parses the declarations and documentation comments in a set of JavaFX Script source files and produces a corresponding set of HTML pages describing (by default) the public and protected classes, attributes, and functions. You can use it to generate Application Programming Interface documentation or implementation documentation for a set of source files. This tool is intentionally very similar to the Java javadoc tool.

You can run the javafxdoc tool on entire packages, individual source files, or both. When documenting entire packages, you can either use subpackages for traversing recursively down from a top-level directory, or pass in an explicit list of package names. When documenting individual source files, you pass in a list of source ( .fx) file names.

Processing Source Files

The javafxdoc tool processes files that end in .fx, plus other files described under Source files. If you run the javafxdoc tool by explicitly passing in individual source filenames, you can determine exactly which .fx files are processed. However, that is not how most developers want to work, as it is simpler to pass in package names.

You can run javafxdoc three ways without explicitly specifying the source filenames:

In these cases, the javafxdoc tool processes a .fx file only if its name, after stripping off the .fx suffix, is a legal class name. For details, see Identifiers.

Processing Links

During a run, the javafxdoc tool automatically adds cross-reference links to package, class and member names that are being documented as part of that run. Links appear in several places:

You can add hyperlinks to existing text for classes not included on the command line (but generated separately) by way of the link and linkoffline options.

Other Processing Details

The javafxdoc tool produces one complete document each time it is run. It cannot do incremental builds, that is, it cannot modify or directly incorporate results from previous runs of the javafxdoc tool. However, it can link to results from other runs, as noted above. The javafxdoc tool also has the option to save the intermediate data from a set of packages in an XML file. These intermediate files can be included with a javafxdoc task, to incorporate previous runs into a complete document.

As implemented, the javafxdoc tool requires and relies on the JavaFX Script compiler to do its job. The javafxdoc tool calls part of javafxc to compile the declarations, ignoring the member implementation. It builds a rich internal representation of the classes, including the class hierarchy, and use relationships, then generates the HTML from that. The javafxdoc tool also picks up user-supplied documentation from documentation comments in the source code.

In fact, the javafxdoc tool can run on .fx source files that are pure stub files with no method bodies. This means you can write documentation comments and run the javafxdoc tool in the earliest stages of design while creating the API, before writing the implementation.

When the javafxdoc tool builds its internal structure for the documentation, it loads all referenced classes. Because of this process, the javafxdoc tool must be able to find all referenced classes, whether bootstrap classes, extensions, or user classes. For more about this requirement, see How Classes Are Found. In general, classes you create must either be loaded as an extension or reside in the class path for the javafxdoc tool.

Documentation Comments

Automatic Copying of Method Comments

The javafxdoc tool has the ability to copy or inherit function comments in classes under the following circumstances. Note that attributes do not inherit doc comments.

javafxdoc Tags

The javafxdoc tool parses special tags when they are embedded within a JavaFX Script doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an at sign (@) and are case-sensitive, they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line after any leading spaces and an optional asterisk, or it is treated as normal text. By convention, tags with the same name are grouped together. For example, put all @see tags together.

The current tags are:


Copyright © 2009 Sun Microsystems, Inc. All rights reserved.

Sun is required to provide certain third party notices. Please see Third Party Notices for the text of such notices.






Spec-Zone.ru - all specs in one place