[caffeine-hx] r746 committed - Removal of --ignoreRoot directive. Use --deny=/

[caffe...@googlecode.com]

Revision: 746
Author: damon...@gmail.com
Date: Mon Aug 6 09:40:09 2012
Log: Removal of --ignoreRoot directive. Use --deny=/


http://code.google.com/p/caffeine-hx/source/detail?r=746

Modified:
/trunk/projects/chxdoc/src/CHANGES
/trunk/projects/chxdoc/src/README
/trunk/projects/chxdoc/src/chxdoc/ChxDocMain.hx
/trunk/projects/chxdoc/src/chxdoc/Filters.hx
/trunk/projects/chxdoc/src/chxdoc/Setup.hx

=======================================
--- /trunk/projects/chxdoc/src/CHANGES Fri Aug 3 20:43:29 2012
+++ /trunk/projects/chxdoc/src/CHANGES Mon Aug 6 09:40:09 2012
@@ -17,6 +17,7 @@
- --file added, no longer will command line blindly accept
flash.xml,flash,remap syntax
- -f which was for 'filter' was redundant syntax for --exclude. Both
removed.
- -f changed to shortcut for --file
+ - --includeOnly removed for new filtering
- New filtering engine created
- Added --allow and --deny for filtering
- Changed --generateTodoFile to --generateTodo
=======================================
--- /trunk/projects/chxdoc/src/README Fri Aug 3 20:43:29 2012
+++ /trunk/projects/chxdoc/src/README Mon Aug 6 09:40:09 2012
@@ -16,7 +16,7 @@

= Installation =

-CHXDOC is now installed from haxelib. It must be compiled on your local
system, so the program can locate the default template.
+CHXDOC is installed from haxelib. It is compiled on your system, and can
be installed anywhere.

{{{
haxelib install chxdoc
@@ -44,7 +44,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
@@ -59,17 +59,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 settings are chained, so multiple _--config_ switches can be
specified.
+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;
@@ -84,6 +122,108 @@
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
+
+--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
@@ -113,9 +253,11 @@
@requires
@return (or @returns)
@see
+@since
@throws
@todo
@type
+@version
}}}

@author text
@@ -141,6 +283,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)
@@ -151,11 +296,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.

@@ -168,9 +313,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:

=======================================
--- /trunk/projects/chxdoc/src/chxdoc/ChxDocMain.hx Fri Aug 3 20:43:29 2012
+++ /trunk/projects/chxdoc/src/chxdoc/ChxDocMain.hx Mon Aug 6 09:40:09 2012
@@ -122,7 +122,6 @@
public static var writeWebConfig : Bool = false;
static var createConfig : Bool = false;

-
//////////////////////////////////////////////
// Pass 1 //
//////////////////////////////////////////////
@@ -726,6 +725,9 @@
config.showPrivateMethods ||
config.showPrivateVars)
config.developer = true;
+
+ if( Filters.isFiltered("/", false) )
+ config.ignoreRoot = true;
}

public static function handleArg(arg:String, nextArg:String->String,
isXml:Bool) {
@@ -744,6 +746,8 @@
case "--config":
Setup.loadConfigFile(nextArg(fileErr("config")));
case "--createConfig":
+ if(isXml)
+ throw "createConfig is not permitted in xml files";
createConfig = true;
case "--dateLong":
config.dateLong = nextArg("Expected date format for --dateLong");
@@ -817,9 +821,6 @@
case "--htmlFileExtension":
config.htmlFileExtension = nextArg("Expected file extension for html
files");
Setup.writeVal("htmlFileExtension", config.htmlFileExtension);
- case "--ignoreRoot":
- config.ignoreRoot = getBool(nextArg(boolErr("ignoreRoot")));
- Setup.writeVal("ignoreRoot", config.ignoreRoot);
case "--installCssFile":
config.installImagesDir = getBool(nextArg(boolErr("installCssFile")));
Setup.writeVal("installCssFile", config.installCssFile);
@@ -941,7 +942,6 @@
println("\t--headerTextFile=/path/to/file Type pages header text from
file");
println("\t--help This usage list");
println("\t--htmlFileExtension=html Extension for generated html files");
- println("\t--ignoreRoot=[true|false] Toggle display of root classes");
println("\t--installCssFile=[true|false] Install stylesheet from
template");
println("\t--installImagesDir=[true|false] Install images from
template");
println("\t--installTemplate=[true|false] Install stylesheet and images
from template");
@@ -973,7 +973,7 @@
println("\tinput.xml[,platform[,remap]");
println("\tXml files are generated using the -xml option when compiling
haxe projects. ");
println("\tplatform - generate docs for a given platform" );
- println("\tremap - change all references of 'remap' to 'package'");
+ println("\tremap - change all references of 'remap' to 'platform'");
println("\n Sample usage:");
println("\tchxdoc -f flash9.xml,flash,flash9 --file=php.xml,php");
println("\t\tWill transform all references to flash.* to flash9.*");
=======================================
--- /trunk/projects/chxdoc/src/chxdoc/Filters.hx Fri Aug 3 20:43:29 2012
+++ /trunk/projects/chxdoc/src/chxdoc/Filters.hx Mon Aug 6 09:40:09 2012
@@ -93,15 +93,15 @@
* @todo What were the paths ending with "__"?
**/
public static function isFiltered( path : String, isPackage : Bool ) {
- if(isPackage) {
- if(path.charAt(path.length-1) != ".")
- path += ".";
- }
if( isPackage && path == "Remoting" )
return true;
if( StringTools.endsWith(path,"__") )
return true;

+ if(isPackage) {
+ if(path.charAt(path.length-1) != ".")
+ path += ".";
+ }
for(r in rules) {
if(matches(path, r)) {
return switch(r.policy) {
@@ -121,7 +121,7 @@
return true;
// "root types" is set on pass1 in ChxDocMain and tested
PackageHandler.pass4
// and used in the templates
- if( rule.path == "/" && (path.indexOf(".") < 0 ||
StringTools.startsWith(path,"root types"))) {
+ if( rule.path == "/" && (path == "/" || path.indexOf(".") < 0 ||
StringTools.startsWith(path,"root types")) ) {
return true;
}
if( rule.path.charAt(rule.path.length-1) == "." ) {
=======================================
--- /trunk/projects/chxdoc/src/chxdoc/Setup.hx Fri Aug 3 20:43:29 2012
+++ /trunk/projects/chxdoc/src/chxdoc/Setup.hx Mon Aug 6 09:40:09 2012
@@ -265,7 +265,6 @@
setVal("dateShort", "%Y-%m-%d");
setVal("dateLong", "%a %b %d %H:%M:%S %Z %Y");

- setVal("ignoreRoot", false);
setVal("developer", false);
setVal("showAuthorTags", false);
setVal("showMeta",true);
@@ -336,7 +335,6 @@
setval("footerTextFile", c.footerTextFile, true);
setval("dateShort", c.dateShort, true);
setval("dateLong", c.dateLong, true);
- setval("ignoreRoot", c.ignoreRoot, true);
setval("showAuthorTags", c.showAuthorTags, true);
setval("showPrivateClasses", c.showPrivateClasses, true);
setval("showPrivateTypedefs", c.showPrivateTypedefs, true);
@@ -597,8 +595,6 @@
mkc("Turns on all show* values, regardless of their value. Should come
before any show* entries");
case "generateTodo":
mkc("Turn on todo generation. and file to output todo list to");
- case "ignoreRoot":
- mkc("Ignore classes in the root package");
case "htmlFileExtension":
mkc("File extension for html documentation files");
case "title":