[caffeine-hx] r739 committed - Edited wiki page ChxDoc through web user interface.

[caffe...@googlecode.com]

Revision: 739
Author: damon...@gmail.com
Date: Sun Aug 5 10:25:56 2012
Log: Edited wiki page ChxDoc through web user interface.
http://code.google.com/p/caffeine-hx/source/detail?r=739

Modified:
/wiki/ChxDoc.wiki

=======================================
--- /wiki/ChxDoc.wiki Fri Aug 3 15:27:21 2012
+++ /wiki/ChxDoc.wiki Sun Aug 5 10:25:56 2012
@@ -45,7 +45,7 @@

{{{
chxdoc -o docs_dev --developer=true -f myproject.xml
-chxdoc -o docs --templateDir=templates/release -f myproject.xml
+chxdoc -o docs --templatesDir=/chxdoc/templates --template=default -f
myproject.xml
}}}

Two versions of the documentation would be created, one with all the
private data
@@ -60,17 +60,55 @@
{{{
chxdoc -o docs --tmpDir=_chxdoctmp
--templateDir=../chxdoc/templates/default --installTemplate=true
--developer=true flash9.xml,flash9,flash neko.xml,neko js.xml,js
}}}
+
+= Configuration =
+
+Configuration of chxdoc is done using xml files. When run for the first
time, chxdoc
+will create a file _.chxdoc_ in your home directory. This file is always
loaded when
+chxdoc is run. A custom chxdoc config xml file can be created then
specified by the
+_--config=mycfg.xml_ command line switch.
+
+Xml config is chained. The first file loaded is your home .chxdoc file.
After that,
+anything that is specified on the command line overrides current settings,
which
+allows for sourcing multiple xml files and overriding any setting by using
command
+line switches.
+
+The order is
+ * Your home .chxdoc file is loaded and parsed
+ * Command line arguments from left to right
+
+For example {{{chxdoc -o docs --mergeMeta=true -f flash9.xml
--config=project.chxdoc }}}
+will load the home .chxdoc file, parse it, then set output to _docs_, then
set _mergeMeta_
+to true, then load the xml config file _project.chxdoc_. If that last file
sets _mergeMeta_
+to false, that will override the settings in _project.chxdoc_, the command
line _--mergeMeta_,
+and the default setting in your home .chxdoc.

= Options =

---config=[[xmlpath]]
+Most xml configuration items can be specified on the command line using
the element name and value.
+For example {{{<developer value="true">}}} is specified as
_--developer=true_ on the command line.
+When using switches on the command line, the equals sign is optional, but
is shown here for clarity.
+
+--allow={{{[class[,orPkg[,Paths]]]]}}}
+ Allow rule for filter chain
+
+--config=xmlfile
Loads a chxdoc configuration file. This option can be specified multiple
times,
allowing configuration overlays processed in the order on the command
line. See
'createConfig'.

---createConfig
+--createConfig (not available in xml files)
This option writes a default chxdoc config file as chxdocConfig.xml.

+--dateLong="%a %b %d %H:%M:%S %Z %Y"
+ Format for long dates
+
+--dateShort="%Y-%m-%d"
+ Format for short dates
+
+--deny={{{[class[,orPkg[,Paths]]]}}}
+ Deny rule for filter chain
+
--developer=[true|false]
This tag is a shortcut to setting the following switches:
--showAuthorTags=bool;
@@ -85,6 +123,111 @@
in a developer build with:
--developer=true --showAuthorTags=false

+-f, --file=name{{{[,platform[,remap]]}}}
+ Input xml files. _platform_ and _remap_ are optional. If remap is
specified, all package
+ references that match _remap_ are translated to _platform_.
+
+--footerText="text"
+ Text that will be added to footer of Type pages
+
+--footerTextFile=/path/to/file
+ Type pages footer text from file
+
+--generateTodoFile=[true|false]
+ Generate the todo html file
+
+--headerText="text"
+ Text that will be added to header of Type pages
+
+--headerTextFile=/path/to/file
+ Type pages header text from file
+
+--help (not available in xml)
+ Command line reference
+
+--htmlFileExtension=html
+ Extension for generated html files
+
+--ignoreRoot=[true|false]
+ Toggle display of root classes
+
+--installCssFile=[true|false]
+ Install stylesheet from template to output directory
+
+--installImagesDir=[true|false]
+ Install images from template to output directory
+
+--installTemplate=[true|false]
+ Install stylesheet and images from template to output directory
+
+--macros=file.mtt
+ Temploc macro file. (default macros.mtt)
+
+--mergeMeta=[true|false]
+ Merge metadata tags to doc tags for similar names. If --showMeta is off,
this will
+ have no effect
+
+-o, --output=outputdir
+ Sets the output directory (defaults to ./docs)
+
+--policy={{{[allow|deny]}}}
+ Sets the default policy for the filter chain
+
+--showAuthorTags=[true|false]
+ Toggles showing @author contents
+
+--showMeta=[true|false]
+ Toggle showing haxe metadata
+
+--showPrivateClasses=[true|false]
+ Toggle private classes display
+
+--showPrivateTypedefs=[true|false]
+ Toggle private typedef display
+
+--showPrivateEnums=[true|false]
+ Toggle private enum display
+
+--showPrivateMethods=[true|false]
+ Toggle private method display
+
+--showPrivateVars=[true|false]
+ Toggle private var display
+
+--showTodoTags=[true|false]
+ Toggle showing @todo tags in type documentation
+
+--stylesheet=file
+ Sets the stylesheet relative to the outputdir
+
+--subtitle=string
+ Set the package subtitle
+
+--template=name
+ Template name relative to --templatesDir (default is 'default')
+
+--templatesDir=path
+ Set the base directory for templates
+
+--title=string
+ Set the package title
+
+--tmpDir=path
+ Path for tempory file generation (default ./__chxdoctmp)
+
+-v,--verbose=[true|false]
+ Turns on verbose mode
+
+--webPassword=[pass]
+ Sets a web password for ?reload and ?showconfig
+
+--writeWebConfig
+ Parses everything, serializes and outputs .chxdoc.hsd
+
+--xmlBasePath=path
+ Set a default path to xml files
+
+
= Using Tags =

Chxdoc adds support for @ tags in your source code comments. To use them,
they
@@ -114,9 +257,11 @@
@requires
@return (or @returns)
@see
+@since
@throws
@todo
@type
+@version
}}}

@author text
@@ -142,6 +287,9 @@
@see Description
Adds description as a source to view

+@since Date/Revision/Version
+ A description of when the item was added to the project
+
@throws full_class_path Description
Will link html documentation to the class path provided, so it
must be a fully qualified class path. (haxe.io.Eof)
@@ -152,11 +300,11 @@
@type Description
For adding descriptions for anonymous types

+@version Description
+ A version number
+
= Package and Type filtering =

-Filtering completely changed in chxdoc 1.2 to a more complete way of
describing what
-exactly you need to generate documentation for.
-
Filtering is done with a series of rules that match either package paths
or class paths. Each
filter has a policy, which is either to "allow" or "deny" building of
documentation for the path.

@@ -169,9 +317,12 @@
</filters>
}}}

-Filters start with a default policy, which is seen in the top <filters>
element. If the class path
-goes through all the <filter> entries without matching, the default policy
is applied (which is
-'allow' in this example.)
+Filters start with a default policy, which is seen in the top {{{<filters
policy="allow">}}}
+element, or specified on the command line by the _--policy=allow_ switch.
This is the overall
+default policy used when a package does not match any filter, so if the
class path
+goes through all the {{{<filter>}}} entries without matching, the default
policy is applied. When
+set to _allow_, by default the documentation will be generated. Conversely
if it is set
+to _deny_, and does not match any rule, no documentation for it will be
created.

To create documentation for only a specific package... say chxdoc itself,
it might look like this: