metaonly module xdc.tools.cdoc.Main

Command implementation

cdoc is a package documentation generation utility. It builds a directory of browsable HTML documentation using the meta- information stored in RTSC packages. [ more ... ]
Configuration settings sourced in xdc/tools/cdoc/Main.xdc
var Main = xdc.useModule('xdc.tools.cdoc.Main');
module-wide config parameters
        '[-od:dir] [-title text] [--start package] [--indexonly] [--doxytags file] [--doxybase dir] [-h] [-n] [-b] [-s] [-P pkg-dir...|-Pr repo-dir...|-A]'
    ];
module-wide functions
    Main.exec// xs script entry point(Any args) returns Any
    Main.main// xs shell entry point(Any args) returns Any
per-instance config parameters
    var params = new Main.Params// Instance config-params object;
        params.bopt// Generate a single "big" output = Bool false;
        params.doxybase// The directory containing doxygen html files = String null;
        params.iopt// Generate index and table of contents only = Bool false;
        params.nopt// Generate nodoc'd docs = Bool false;
        params.outdir// Place the generated files in the named directory = String null;
        params.popt// The subsequent directories are package directories = Bool false;
        params.qopt// Quiet mode = Bool false;
        params.sopt// Include .xdc file sources = Bool false;
        params.start// Set start page to specified package = String null;
        params.style// Use specified style sheet = String null;
per-instance functions
    inst.run// Underlying implementation of the command(Cmdr.Instance cmdr, String[] args) returns Any
 
DETAILS
cdoc is a package documentation generation utility. It builds a directory of browsable HTML documentation using the meta- information stored in RTSC packages.
This utility is invoked via the XDCtools xs command. In the examples below we assume that the alias cdoc is defined as follows:
      $(XDCROOT)/xs xdc.tools.cdoc
where $(XDCROOT) is the installation directory of the XDCtools toolset.
EXAMPLES
In the examples below we assume that the alias cdoc is defined as $(XDCROOT)/xs xdc.tools.cdoc, where $(XDCROOT) is the installation directory of the XDCtools toolset.
1. To generate documentation for the package in the current working directory:
      cdoc
Since no package is specified and no output directory is specified, documentation is generated for the package in the current working directory and the output is placed in the package's ./package/cdoc sub-directory.
2. To generate documentation with the title "My Packages" for all packages installed in the myPackages repository:
      cdoc -title "My Packages" -Pr myPackages
Since no output directory was specified and documentation will be for more than one package, the generated files are placed in the directory ./cdoc.
3. To generate documentation for the package located in ./ti/bios and put results in the directory ./html.
      cdoc -od:html -P ti/bios
NOTE
cdoc processes the XML files that are generated *after* a package is built (actually after the .interfaces goal is built). One must first build a package before generating its documentation. If you change a .xdc file and re-run cdoc without rebuilding the package, the change in the .xdc file will not show up in the generated docs.
When interatively updating a package's .xdc files and examining the generated documentation, it is useful to define a command alias that first "compiles" the package's .xdc files and then runs the cdoc tool. For example, if your shell is Korn shell compatible, the following command alias ensures that any changes in .xdc files will show up in the generated documents:
      function cdoc {
          $XDCROOT/xdc .interfaces
          $XDCROOT/xs xdc.tools.cdoc $*
      }
 
config Main.usage  // module-wide

Usage for this command

Configuration settings
Main.usage = String[] [
    '[-od:dir] [-title text] [--start package] [--indexonly] [--doxytags file] [--doxybase dir] [-h] [-n] [-b] [-s] [-P pkg-dir...|-Pr repo-dir...|-A]'
];
 
 
Main.exec()  // module-wide

xs script entry point

Configuration settings
Main.exec(Any args) returns Any
 
DETAILS
This function is called from within other XDCscript scripts and performs the same operations as main() except that, rather than output the return value of inst.run(), this value is simply returned to the caller of exec().
 
Main.main()  // module-wide

xs shell entry point

Configuration settings
Main.main(Any args) returns Any
 
DETAILS
This function
  • creates a no-arg instance, inst, of the module inheriting this interface;
  • parses command line arguments placing all options in the config params of the inheriting module;
  • creates a xdc.tools.Cmdr instance, cmdr;
  • calls inst.run() with the cmdr and any command line command line arguments not parsed as options; and
  • outputs the return result from inst.run()
Instance Config Parameters

Configuration settings
var params = new Main.Params;
// Instance config-params object
    params.aopt = Bool false;
    // Generate documentation for all packages on the package path
    params.bopt = Bool false;
    // Generate a single "big" output
    params.doxybase = String null;
    // The directory containing doxygen html files
    params.doxytags = String null;
    // Process doxygen links, using this argument as the tag file
    params.hopt = Bool false;
    // Generate html pages only, not table of contents or index
    params.iopt = Bool false;
    // Generate index and table of contents only
    params.nopt = Bool false;
    // Generate nodoc'd docs
    params.outdir = String null;
    // Place the generated files in the named directory
    params.popt = Bool false;
    // The subsequent directories are package directories
    params.qopt = Bool false;
    // Quiet mode
    params.ropt = Bool false;
    // The subsequent directories are repositories of packages
    params.sopt = Bool false;
    // Include .xdc file sources
    params.start = String null;
    // Set start page to specified package
    params.style = String null;
    // Use specified style sheet
    params.title = String null;
    // Generated HTML pages will show the string in the page title
 
config Main.Params.aopt  // instance

Generate documentation for all packages on the package path

Configuration settings
var params = new Main.Params;
  ...
params.aopt = Bool false;
 
 
config Main.Params.bopt  // instance

Generate a single "big" output

Configuration settings
var params = new Main.Params;
  ...
params.bopt = Bool false;
 
 
config Main.Params.doxybase  // instance

The directory containing doxygen html files

Configuration settings
var params = new Main.Params;
  ...
params.doxybase = String null;
 
 
config Main.Params.doxytags  // instance

Process doxygen links, using this argument as the tag file

Configuration settings
var params = new Main.Params;
  ...
params.doxytags = String null;
 
 
config Main.Params.hopt  // instance

Generate html pages only, not table of contents or index

Configuration settings
var params = new Main.Params;
  ...
params.hopt = Bool false;
 
 
config Main.Params.iopt  // instance

Generate index and table of contents only

Configuration settings
var params = new Main.Params;
  ...
params.iopt = Bool false;
 
 
config Main.Params.nopt  // instance

Generate nodoc'd docs

Configuration settings
var params = new Main.Params;
  ...
params.nopt = Bool false;
 
 
config Main.Params.outdir  // instance

Place the generated files in the named directory

Configuration settings
var params = new Main.Params;
  ...
params.outdir = String null;
 
 
config Main.Params.popt  // instance

The subsequent directories are package directories

Configuration settings
var params = new Main.Params;
  ...
params.popt = Bool false;
 
DETAILS
Generates documentation for each of the specified packages.
 
config Main.Params.qopt  // instance

Quiet mode

Configuration settings
var params = new Main.Params;
  ...
params.qopt = Bool false;
 
 
config Main.Params.ropt  // instance

The subsequent directories are repositories of packages

Configuration settings
var params = new Main.Params;
  ...
params.ropt = Bool false;
 
DETAILS
Generates documentation for all packages rooted in each of the specified repositories.
 
config Main.Params.sopt  // instance

Include .xdc file sources

Configuration settings
var params = new Main.Params;
  ...
params.sopt = Bool false;
 
DETAILS
In the generated documentation for each .xdc file, link to a pretty-printed view of the .xdc file source text.
 
config Main.Params.start  // instance

Set start page to specified package

Configuration settings
var params = new Main.Params;
  ...
params.start = String null;
 
DETAILS
The opening page is, by default, the documentation for the alphabetically first package processed. This option allows you to explicitly specify the package used.
If "" is specified, the start page will be blank.
If the package specified is not processed, no warning or error results; it is assumed that when the documentation is used the specified package documentation will exist.
 
config Main.Params.style  // instance

Use specified style sheet

Configuration settings
var params = new Main.Params;
  ...
params.style = String null;
 
 
config Main.Params.title  // instance

Generated HTML pages will show the string in the page title

Configuration settings
var params = new Main.Params;
  ...
params.title = String null;
 
 
Main.run()  // instance

Underlying implementation of the command

Configuration settings
inst.run(Cmdr.Instance cmdr, String[] args) returns Any
 
DETAILS
Since this method is used to support both command line tools and other XDCscript scripts, it is important to avoid explicit termination of the JVM via java.lang.System.exit(); doing so precludes callers from handling failures.
Implementations should instead call
generated on Wed, 09 Apr 2014 00:37:49 GMT