more documentation and some minor fixes

.gitignore

@@ -1,5 +1,6 @@
 bin
 doc/pages
 doc/xml
+doc/dox
 .DS_Store
 *.sublime-*

doc/build_doc.hxml

@@ -2,6 +2,9 @@
 --no-output
 -D doc-gen
 -D display
+-D dox
+-dce no
+-lib thx.core
 ImportAll
 
 --each

doc/doc.hxml

@@ -1,5 +1,6 @@
 -cmd rm -rf xml/*
 -cmd haxe build_doc.hxml
 -cmd rm -rf pages
--cmd haxelib run dox -r / -o pages -i xml --title "thx.core" -in thx
+-cmd haxelib run dox -r / -o pages -i xml --title "thx.core" -in thx #--template-path dox/templates
+#-cmd cp -r dox/resources/* pages
 -cmd static pages

src/thx/core/Arrays.hx

@@ -9,7 +9,7 @@ import haxe.macro.ExprTools;
 #end
 
 /**
-It provides additional extension methods on top of the `Array` type.
+`Arrays` provides additional extension methods on top of the `Array` type.
 
 Note that some of the examples imply `using thx.core.Arrays;`.
 **/

src/thx/core/Dates.hx

@@ -1,5 +1,8 @@
 package thx.core;
 
+/**
+`Dates` provides additional extension methods on top of the `Date` type.
+**/
 class Dates {
 /**
 It compares two dates.

src/thx/core/Dynamics.hx

@@ -1,15 +1,21 @@
 package thx.core;
 
+/**
+`Dynamics` provides additional extension methods on any type.
+**/
 class Dynamics {
-  public static function same<T1, T2>(a : T1, b : T2) : Bool {
-    // quick check
-    if(untyped a == b)
-      return true;
-
+/**
+Structural and recursive equality.
+**/
+  public static function equals<T1, T2>(a : T1, b : T2) : Bool {
     // type check
     if(!Types.sameType(a, b))
       return false;
 
+    // quick check
+    if(untyped a == b)
+      return true;
+
     switch Type.typeof(a) {
       case TFloat, TNull, TInt, TBool:
         return false;
@@ -32,7 +38,7 @@ class Dynamics {
           if (aa.length != ab.length)
             return false;
           for (i in 0...aa.length)
-            if (!same(aa[i], ab[i]))
+            if (!equals(aa[i], ab[i]))
               return false;
           return true;
         }
@@ -50,7 +56,7 @@ class Dynamics {
           if (ka.length != kb.length)
             return false;
           for (key in ka)
-            if (!hb.exists(key) || !same(ha.get(key), hb.get(key)))
+            if (!hb.exists(key) || !equals(ha.get(key), hb.get(key)))
               return false;
           return true;
         }
@@ -64,19 +70,24 @@ class Dynamics {
             return false;
 
           for (i in 0...va.length)
-            if (!same(va[i], vb[i]))
+            if (!equals(va[i], vb[i]))
               return false;
           return true;
         }
 
+        // custom class with equality method
+        var f;
+        if(Reflect.hasField(a, 'equals') && Reflect.isFunction(f = Reflect.field(a, 'equals')))
+          return Reflect.callMethod(a, f, [b]);
+
         // custom class
         var fields = Type.getInstanceFields(Type.getClass(a));
         for (field in fields) {
           var va = Reflect.field(a, field);
           if (Reflect.isFunction(va))
             continue;
           var vb = Reflect.field(b, field);
-          if(!same(va, vb))
+          if(!equals(va, vb))
             return false;
         }
         return true;
@@ -92,7 +103,7 @@ class Dynamics {
         var pa = Type.enumParameters(cast a),
           pb = Type.enumParameters(cast b);
         for (i in 0...pa.length)
-          if (!same(pa[i], pb[i]))
+          if (!equals(pa[i], pb[i]))
             return false;
         return true;
       case TObject  :
@@ -107,7 +118,7 @@ class Dynamics {
           if(Reflect.isFunction(va))
             continue;
           var vb = Reflect.field(b, field);
-          if(!same(va, vb))
+          if(!equals(va, vb))
             return false;
         }
         if (fb.length > 0)
@@ -127,7 +138,7 @@ class Dynamics {
           if (aa.length != ab.length)
             return false;
           for (i in 0...aa.length)
-            if (!same(aa[i], ab[i]))
+            if (!equals(aa[i], ab[i]))
               return false;
           return true;
         }

src/thx/core/ERegs.hx

@@ -1,7 +1,14 @@
 package thx.core;
 
+/**
+`ERegs` provides helper methods to use together with `EReg`.
+**/
 class ERegs {
 	static var ESCAPE_PATTERN = ~/([-[\]{}()*+?.,\\^$|#\s])/g;
+
+/**
+It escapes any characer in a string that has a special meaning when used in a regula expression.
+**/
 	public static function escape(text : String) : String
 		return ESCAPE_PATTERN.replace(text, "\\$1");
 }

src/thx/core/Error.hx

@@ -3,7 +3,15 @@ package thx.core;
 import haxe.PosInfos;
 import haxe.CallStack;
 
+/**
+
+**/
 class Error #if js extends js.Error #end {
+/**
+It creates an instance of Error from any value.
+
+If `err` is already an instance of `Error`, it is returned and nothing is created.
+**/
   public static function fromDynamic(err : Dynamic, ?pos : PosInfos) : Error {
     if(Std.is(err, Error))
       return cast err;

src/thx/core/UUID.hx

@@ -1,13 +1,14 @@
 package thx.core;
 
+/**
+Helper class to generate [UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) strings (version 4).
+**/
 class UUID {
-  static var itoh = '0123456789ABCDEF';
-
   static inline function random()
     return Math.floor(Math.random()*0x10);
 
   static inline function srandom()
-    return ''+random();
+    return '${random()}';
 
   public static function create() {
     var s = [];