Project configuration

Modified on Wednesday, 23 December 2009 07:56 by Administrator — Categorized as: Uncategorized

Table of Contents [Hide/Show]


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:

Image

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:



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"