Project configuration

Project configuration files specify all options related to parsing files from, and producing documentation of ECMADoc projects. The configuration files are XML files, and a schema file is provided that you can use to create and validate new configuration files if you are writing them by hand.

Example ¶

This example shows configuration of a project called 'Aeon'.

<?xml version="1.0" encoding="utf-8"?>
<project name="Aeon" xmlns="http://www.cycle99.com/tools/ecmadoc">
  <output path="aeon" fileExtension=".html" groupBy="type">
    <theme>default</theme>
  </output>
  <log fileName="jsdoc.log" format="text" severity="debug" />
  <sources>
    <file>$Resources/Base/javascript.js</file>
    <folder extensions="js">../aeon</folder>
  </sources>
  <options
    useMultipleInheritance="false"
    documentAnonymousFunctions="false"
    documentPrivateMembers="false"
    outputMembersOnSinglePage="true"/>
</project>

Structure ¶

The following sections describe each node and attribute of the configuration XML file.

Project element ¶

Required. This is the root node that contains all other content.

<project name="Aeon" xmlns="http://www.cycle99.com/tools/ecmadoc">
  ...
</project>

name attribute ¶

Specifies the name of the project.

name="Aeon"

Output element ¶

Required. Specifies options related to generating output documentation. Possible attributes are:

<output path="aeon" fileExtension=".html" groupBy="type">
  <theme>default</theme>
</output>

path attribute ¶

Specifies the directory in which the documentation will be generated. If this is a relative path, it will be calculated relative to the location of the configuration file.

path="aeon"

fileExtension attribute ¶

Specifies the file extension that all generated files will have. Typically this will be '.htm' or '.html'.

fileExtension="html"

groupBy attribute ¶

Possible values are 'type' and 'none'. Controls the appearance of members in the project tree on the contents page. If 'type' option is specified, the members of the same type will be grouped in folders under types they belong to.

groupBy="type"

This image compares the appearance of ungrouped members with members grouped by type:

Theme element ¶

Required. Specifies the theme to use for generated HTML documentation.

<theme>default</theme>

Log element ¶

Required. Specifies the logging options.

<log fileName="jsdoc.log" format="text" severity="debug" />

fileName attribute ¶

The name of the file in which output log messages will be saved. This file will be saved in the same directory as the output documentation.

fileName="jsdoc.log"

format attribute ¶

Specifies the format in which the log messages will be stored in the log file. Currently only text is supported.

format="text"

severity attribute ¶

Specifies the minimum severity of the log messages for them to appear in the output log. Possible values (ordered by severity, from lowest to highest) are:

debug
info
warning
error
fatal

severity="debug"

Sources element ¶

Required. Specifies the files and/or folders that the project consists of.

<sources>
  <file>$Resources/Base/javascript.js</file>
  <folder extensions="html">../aeon/aeon.js</folder>
</sources>

File element ¶

Specifies a single file that is a part of the project.

<file>$Resources/Base/javascript.js</file>

Folder element ¶

Specifies a single folder that is a part of the project.

<folder extensions="js">../aeon</folder>

extensions attribute ¶

Specifies file extensions of files that should be included in the project. This value is treated as a comma separated list. Default value is 'js'.

extensions="js"

Options element ¶

Required. Specifies various program options.

<options
    useMultipleInheritance="false"
    documentAnonymousFunctions="false"
    documentPrivateMembers="false"
    outputMembersOnSinglePage="true"/>

useMultipleInheritance attribute ¶

If true, members in source can have multiple parent classes. This is to accommodate certain techniques that extend JavaScript with custom inheritance mechanism, which in turn may provide multiple inheritance capabilities. The default value is false.

useMultipleInheritance="false"

documentAnonymousFunctions attribute ¶

If true, anonymous methods with neither the name or an alias variable pointing to them will also appear in the result documentation. The default value is false.

documentAnonymousFunctions="false"

documentPrivateMembers attribute ¶

If true, private members will appear in the output. Note that you will still have the option to toggle them in the interface. The default value is false.

documentPrivateMembers="false"

outputMembersOnSinglePage attribute ¶

This option controls whether the members of a type should appear on the same page as their containing type, or on separate pages. With this option set to true, all class properties, methods etc will appear on the same page as the class itself. With this option set to false, each member will appear on a separate page.

If you choose for all members on one page, the number of html files in the output will be smaller, but the pages themselves may potentially be quite large. With every member on its own page the pages will likely be small and concise, but the number of files will be much bigger. You should evaluate both approaches and choose the one which better suits your requirements.

outputMembersOnSinglePage="false"