Spec-Zone .ru спецификации, руководства, описания, API

javafxdoc - JavaFX Documentation Utility

• Synopsis
• Description
• Options
• Processing Source Files
• Processing Links
• Other Processing Details
• Documentation Comments
• javafxdoc Tags

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]

options

Command-line options.

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.

@argfiles

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.

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

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.

Options

-link extdocURL

Creates links to existing javadoc-generated documentation of external referenced classes.

-linkoffline extdocURL

This option is a variation of -link. Both options create links to javafxdoc-generated documentation for external referenced classes. Use the -linkoffline option while linking to a document on the web when the javafxdoc tool itself is offline, that is, it cannot access the document through a web connection.

-subpackages package1:package2:...

Generates documentation from source files in the specified packages and recursively in their subpackages.

-sourcepath sourcepathlist

Specifies the search path for finding source files (.fx) when passing package names or -subpackages into the javafxdoc command.

-profile [desktop | mobile ]

Specifies the JavaFX platform. The JavaFX SDK supports desktop and mobile, and defaults to desktop. Internally the -profile option, which specifies the configuration file, which is used for setting environment variables.

-version

Displays the tool version and exits. Note: Use -J-version to get the Java platform version

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:

• Pass in package names.
• Pass in subpackage names.
• Pass in wildcards with source file names.

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:

• Declarations (return types, argument types, field types)
• "See Also" sections generated from @see tags
• In-line text generated from @inline tags
• Exception names generated from @throws tags
• "@comments tags link to members in classes
• Summary tables listing packages, modules, and members
• Package and class inheritance trees
• The index

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

The javafxdoc tool has the ability to copy or inherit function comments in classes. 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 as follows:

{@link package.class#member label}

Inserts an in-line link with visible text label that points to the documentation for the specified package, class or member name of a referenced class. This tag is valid in all doc comments: overview, package, module, class, function and attribute, including the text portion of any tag (such as @return, @param and @deprecated).

@see package.class#member label

Adds a link, with visible text label, that points to the documentation for the specified name in the JavaFX Script API that is referenced. The label is optional. If omitted, the name appears instead as the visible text, suitably shortened. Use -noqualifier to globally remove the package name from this visible text. Use the label when you want the visible text to be different from the autogenerated visible text.

@throws class-name description

The @throws and @exception tags are synonyms. Adds a Throws subheading to the generated documentation, with the class-name and description text. The class-name is the name of the exception that might be thrown by the method. This tag is valid only in the doc comment for a function. Multiple @throws tags can be used in a given doc comment for the same or different exceptions.