documentation.

std/Array.hx

@@ -23,13 +23,31 @@
  * DAMAGE.
  */
 
+/**
+	An Array is a storage for values. You can access it using indexes or
+	with its API. On the server side, it's often better to use a [List] which
+	is less memory and CPU consuming, unless you really need indexed access.
+**/
 extern class Array<T> {
 
+	/**
+		The length of the Array
+	**/
 	property length(default,null) : Int;
 
+	/**
+		Creates a new Array.
+	**/
 	function new() : Void;
 
+	/**
+		Returns a new Array by appending [a] to [this].
+	**/
 	function concat( a : Array<T> ) : Array<T>;
+
+	/**
+		Returns a representation of an array with [sep] for separating each element.
+	**/
 	function join( sep : String ) : String;
 
 	/**
@@ -42,6 +60,9 @@ extern class Array<T> {
 	**/
 	function push(x : T) : Int;
 
+	/**
+		Reverse the order of elements of the Array.
+	**/
 	function reverse() : Array<T>;
 
 	/**
@@ -56,6 +77,12 @@ extern class Array<T> {
 		the array.
 	**/
 	function slice( pos : Int, end : Int ) : Array<T>; // sub
+
+	/**
+		Sort the Array according to the comparison function [f].
+		[f(x,y)] should return [0] if [x == y], [>0] if [x > y]
+		and [<0] if [x < y].
+	**/
 	function sort( f : T -> T -> Int ) : Void;
 
 	/**
@@ -63,6 +90,10 @@ extern class Array<T> {
 	**/
 	function splice( pos : Int, len : Int ) : Array<T>; // removed elts
 	// no toSource (js specific)
+
+	/**
+		Returns a displayable representation of the Array content.
+	**/
 	function toString() : String;
 
 	/**
@@ -71,7 +102,10 @@ extern class Array<T> {
 	function unshift( x : T ) : Void;
 	// no valueOf (js specific)
 
-	/* added */
+	/**
+		Inserts the element [x] at the position [pos].
+		All elements after [pos] are moved one index ahead.
+	**/
 	function insert( pos : Int, x : T ) : Void;
 
 	/**
@@ -79,7 +113,16 @@ extern class Array<T> {
 		Returns false if [x] was not present.
 	**/
 	function remove( x : T ) : Bool;
+
+	/**
+		Returns a copy of the Array. The values are not
+		copied, only the Array structure.
+	**/
 	function copy() : Array<T>;
+
+	/**
+		Returns an iterator of Array values.
+	**/
 	function iterator() : Iterator<T>;
 
 }

std/Date.hx

@@ -23,13 +23,39 @@
  * DAMAGE.
  */
 
+/**
+	The Date class is used for date manipulation. There is some extra functions
+	available in the [DateTools] class.
+**/
 extern class Date
 {
+	/**
+		Creates a new date object.
+	**/
 	function new(year : Int, month : Int, day : Int, hour : Int, min : Int, sec : Int ) : Void;
+
+	/**
+		Returns the timestamp of the date. It's the number of milliseconds
+		elapsed since 1st January 1970.
+	**/
 	function getTime() : Float;
+
+	/**
+		Returns a string representation for the Date, by using the
+		standard format [YYYY-MM-DD HH:MM:SS]. See [DateTools.format] for
+		other formating rules.
+	**/
 	function toString():String;
 
+	/**
+		Returns a Date representing the current local time.
+	**/
 	static function now() : Date;
+
+	/**
+		Returns a Date from a timestamp [t] which is the number of
+		milliseconds elapsed since 1st January 1970.
+	**/
 	static function fromTime( t : Float ) : Date;
 
 	private static function __init__() : Void untyped {

std/DateTools.hx

@@ -23,8 +23,14 @@
  * DAMAGE.
  */
 
+/**
+	The DateTools class contains some extra functionalities for [Date]
+	manipulation. It's stored in a different class in order to prevent
+	the standard [Date] of being bloated and thus increasing the size of
+	each application using it.
+**/
 class DateTools {
-	
+
 	#if neko
 	#else true
 	private static function __jsflash_format_get( d : Date, e : String ) : String {
@@ -32,7 +38,7 @@ class DateTools {
 			case "%":
 				"%";
 			case "C":
-				untyped StringTools.lpad(Std.string(Math.floor(d.getFullYear()/100)),"0",2);
+				untyped StringTools.lpad(Std.string(Std.int(d.getFullYear()/100)),"0",2);
 			case "d":
 				untyped StringTools.lpad(Std.string(d.getDate()),"0",2);
 			case "D":
@@ -82,7 +88,7 @@ class DateTools {
 				throw "Date.format %"+e+"- not implemented yet.";
 		}
 	}
-	
+
 	private static function __jsflash_format( d : Date, f : String ) : String {
 		var r = new StringBuf();
 		var p = 0;
@@ -90,12 +96,13 @@ class DateTools {
 			var np = f.indexOf("%", p);
 			if( np < 0 )
 				break;
-			
+
 			r.add( f.substr(p,np-p) );
 			r.add( __jsflash_format_get(d, f.substr(np+1,1) ) );
-			
+
 			p = np+2;
 		}
+		r.add(f.substr(p,f.length-p));
 		return r.toString();
 	}
 	#end
@@ -104,7 +111,13 @@ class DateTools {
 		static var date_format = neko.Lib.load("std","date_format",2);
 	#end
 
-
+	/**
+		Format the date [d] according to the format [f]. The format
+		is compatible with the [strftime] standard format, except that there
+		is no support in Flash and JS for day and months names (due to lack
+		of proper internationalization API). On haXe/Neko/Windows, some
+		formats are not supported.
+	**/
 	public static function format( d : Date, f : String ) : String {
 		#if neko
 			untyped return new String(date_format(d.__t, f.__s));
@@ -116,8 +129,11 @@ class DateTools {
 		#end
 	}
 
+	/**
+		Returns a Date which time has been changed by [t] seconds.
+	**/
 	public static function delta( d : Date, t : Float ) : Date {
 		return Date.fromTime( d.getTime() + t );
 	}
-	
+
 }

std/EReg.hx

@@ -23,6 +23,11 @@
  * DAMAGE.
  */
 
+/**
+	Regular expressions are a way to find regular patterns into
+	Strings. Have a look at the tutorial on haXe website to learn
+	how to use them.
+**/
 class EReg {
 
 	var r : Void;
@@ -31,6 +36,10 @@ class EReg {
 	var global : Bool;
 	#end
 
+	/**
+		Creates a new regular expression with pattern [r] and
+		options [opt].
+	**/
 	public function new( r : String, opt : String ) {
 		#if neko
 		var a = opt.split("g");
@@ -46,6 +55,10 @@ class EReg {
 		#end
 	}
 
+	/**
+		Tells if the regular expression matches the String.
+		Updates the internal state accordingly.
+	**/
 	public function match( s : String ) : Bool {
 		#if neko
 		var p = regexp_match(r,untyped s.__s,0,s.length);
@@ -69,6 +82,11 @@ class EReg {
 		#end
 	}
 
+	/**
+		Returns a matched group or throw an expection if there
+		is no such group. If [n = 0], the whole matched substring
+		is returned.
+	**/
 	public function matched( n : Int ) : String {
 		#if neko
 		return new String(regexp_matched(r,n));
@@ -81,6 +99,10 @@ class EReg {
 		#end
 	}
 
+	/**
+		Returns the part of the string that was as the left of
+		of the matched substring.
+	**/
 	public function matchedLeft() : String {
 		#if neko
 		var p = regexp_matched_pos(r,0);
@@ -98,6 +120,10 @@ class EReg {
 		#end
 	}
 
+	/**
+		Returns the part of the string that was as the right of
+		of the matched substring.
+	**/
 	public function matchedRight() : String {
 		#if neko
 		var p = regexp_matched_pos(r,0);
@@ -119,6 +145,10 @@ class EReg {
 		#end
 	}
 
+	/**
+		Returns the position of the matched substring within the
+		original matched string.
+	**/
 	public function matchedPos() : { pos : Int, len : Int } {
 		#if neko
 		return regexp_matched_pos(r,0);
@@ -132,6 +162,10 @@ class EReg {
 		#end
 	}
 
+	/**
+		Split a string by using the regular expression to match
+		the separators.
+	**/
 	public function split( s : String ) : Array<String> {
 		#if neko
 		var pos = 0;
@@ -165,6 +199,11 @@ class EReg {
 		#end
 	}
 
+	/**
+		Replaces a pattern by another string. The [by] format can
+		contains [$1] to [$9] that will correspond to groups matched
+		while replacing. [$$] means the [$] character.
+	**/
 	public function replace( s : String, by : String ) : String {
 		#if neko
 		var b = new StringBuf();

std/Hash.hx

@@ -23,8 +23,16 @@
  * DAMAGE.
  */
 
+/**
+	Hashtable over a set of elements, using [String] as keys.
+	Other kind of keys are not possible on all platforms since they
+	can't always be implemented efficiently.
+**/
 class Hash<T> {
 
+	/**
+		Creates a new empty hashtable.
+	**/
 	public function new() : Void {
 		#if flash
 		h = untyped __new__(_global["Object"]);
@@ -40,6 +48,9 @@ class Hash<T> {
 		#end
 	}
 
+	/**
+		Set a value for the given key.
+	**/
 	public function set( key : String, value : T ) : Void {
 		#if flash
 		untyped h[key] = value;
@@ -51,6 +62,9 @@ class Hash<T> {
 		#end
 	}
 
+	/**
+		Get a value for the given key.
+	**/
 	public function get( key : String ) : T {
 		#if flash
 		return untyped h[key];
@@ -62,6 +76,11 @@ class Hash<T> {
 		#end
 	}
 
+	/**
+		Tells if a value exists for the given key.
+		In particular, it's useful to tells if a key has
+		a [null] value versus no value.
+	**/
 	public function exists( key : String ) : Bool {
 		#if flash
 		return untyped h.hasOwnProperty(key);
@@ -73,6 +92,10 @@ class Hash<T> {
 		#end
 	}
 
+	/**
+		Removes a hashtable entry. Returns [true] if
+		there was such entry.
+	**/
 	public function remove( key : String ) : Bool {
 		#if flash
 		if( untyped !h.hasOwnProperty(key) ) return false;
@@ -86,6 +109,9 @@ class Hash<T> {
 		#end
 	}
 
+	/**
+		Returns an iterator of all keys in the hashtable.
+	**/
 	public function keys() : Iterator<String> {
 		#if flash
 		return untyped (__keys__(h)).iterator();
@@ -99,6 +125,9 @@ class Hash<T> {
 		#end
 	}
 
+	/**
+		Returns an iterator of all values in the hashtable.
+	**/
 	public function iterator() : Iterator<T> {
 		#if flash
 		return untyped {
@@ -122,6 +151,10 @@ class Hash<T> {
 		#end
 	}
 
+	/**
+		Returns an displayable representation of the hashtable content.
+	**/
+
 	public function toString() {
 		var s = new StringBuf();
 		s.add("{");

std/IntIter.hx

@@ -23,11 +23,18 @@
  * DAMAGE.
  */
 
+/**
+	Integer iterator. Used for interval implementation.
+**/
 class IntIter {
 
 	var min : Int;
 	var max : Int;
 
+	/**
+		Iterate from [min] (inclusive) to [max] (exclusive).
+		If [max <= min], the iterator will not act as a countdown.
+	**/
 	public function new( min : Int, max : Int ) {
 		this.min = min;
 		this.max = max;

std/List.hx

@@ -23,16 +23,31 @@
  * DAMAGE.
  */
 
+/**
+	A linked-list of elements. The list is composed of two-elements arrays
+	that are chained together. It's optimized so that adding or removing an
+	element doesn't imply to copy the whole array content everytime.
+**/
 class List<T> {
 
 	private var h : Array<Dynamic>;
 	private var q : Array<Dynamic>;
+
+	/**
+		The number of elements in this list.
+	**/
 	public property length(default,null) : Int;
 
+	/**
+		Creates a new empty list.
+	**/
 	public function new() {
 		length = 0;
 	}
 
+	/**
+		Add an element at the end of the list.
+	**/
 	public function add( item : T ) {
 		var x = #if neko
 			untyped __dollar__array(item,null)
@@ -47,6 +62,9 @@ class List<T> {
 		length++;
 	}
 
+	/**
+		Push an element at the beginning of the list.
+	**/
 	public function push( item : T ) {
 		var x = #if neko
 			untyped __dollar__array(item,h)
@@ -59,14 +77,28 @@ class List<T> {
 		length++;
 	}
 
+	/**
+		Returns the first element of the list, or null
+		if the list is empty.
+	**/
 	public function first() : T {
 		return if( h == null ) null else h[0];
 	}
 
+	/**
+		Returns the last element of the list, or null
+		if the list is empty.
+	**/
 	public function last() : T {
 		return if( q == null ) null else q[0];
 	}
 
+
+	/**
+		Removes the first element of the list and
+		returns it or simply returns null if the
+		list is empty.
+	**/
 	public function pop() : T {
 		if( h == null )
 			return null;
@@ -78,10 +110,17 @@ class List<T> {
 		return x;
 	}
 
+	/**
+		Tells if a list is empty.
+	**/
 	public function isEmpty() : Bool {
 		return (h == null);
 	}
 
+	/**
+		Remove the first element that is [== v] from the list.
+		Returns [true] if an element was removed, [false] otherwise.
+	**/
 	public function remove( v : T ) : Bool {
 		var prev = null;
 		var l = h;
@@ -102,6 +141,9 @@ class List<T> {
 		return false;
 	}
 
+	/**
+		Returns an iterator on the elements of the list.
+	**/
 	public function iterator() : Iterator<T> {
 		return {
 			h : h,
@@ -120,6 +162,9 @@ class List<T> {
 		}
 	}
 
+	/**
+		Returns a displayable representation of the String.
+	**/
 	public function toString() {
 		var s = new StringBuf();
 		var first = true;
@@ -137,6 +182,9 @@ class List<T> {
 		return s.toString();
 	}
 
+	/**
+		Join the element of the list by using the separator [sep].
+	**/
 	public function join(sep : String) {
 		var s = new StringBuf();
 		var first = true;
@@ -152,6 +200,10 @@ class List<T> {
 		return s.toString();
 	}
 
+	/**
+		Returns a list filtered with [f]. The returned list
+		will contain all elements [x] for which [f(x) = true].
+	**/
 	public function filter( f : T -> Bool ) {
 		var l2 = new List();
 		var l = h;
@@ -164,6 +216,10 @@ class List<T> {
 		return l2;
 	}
 
+	/**
+		Returns a new list where all elements have been converted
+		by the function [f].
+	**/
 	public function map<X>(f : T -> X) : List<X> {
 		var b = new List();
 		var l = h;

std/Md5.hx

@@ -22,7 +22,12 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  * DAMAGE.
  */
+
+/**
+	Creates a MD5 of a String.
+**/
 class Md5 {
+
 	public static function encode( s : String ) : String{
 		#if neko
 			untyped return new String(base_encode(make_md5(s.__s),"0123456789abcdef".__s));
@@ -33,12 +38,12 @@ class Md5 {
 		#else error
 		#end
 	}
-	
+
 	#if neko
 	static var base_encode = neko.Lib.load("std","base_encode",2);
 	static var make_md5 = neko.Lib.load("std","make_md5",1);
 	#else true
-	
+
 /*
  * A JavaScript implementation of the RSA Data Security, Inc. MD5 Message
  * Digest Algorithm, as defined in RFC 1321.
@@ -53,13 +58,13 @@ class Md5 {
 		return (msb31 << 1) | lsb;
 	}
 
-	private static function bitXOR(a, b){   
+	private static function bitXOR(a, b){
 		var lsb = (a & 0x1) ^ (b & 0x1);
 		var msb31 = (a >>> 1) ^ (b >>> 1);
 		return (msb31 << 1) | lsb;
 	}
 
-	private static function bitAND(a, b){   
+	private static function bitAND(a, b){
 		var lsb = (a & 0x1) & (b & 0x1);
 		var msb31 = (a >>> 1) & (b >>> 1);
 		return (msb31 << 1) | lsb;
@@ -70,7 +75,7 @@ class Md5 {
 		var msw = (x >> 16)+(y >> 16)+(lsw >> 16);
 		return (msw << 16) | (lsw & 0xFFFF);
 	}
-	
+
 	private static function rhex( num ){
 		var str = "";
 		var hex_chr = "0123456789abcdef";
@@ -126,7 +131,7 @@ class Md5 {
 	}
 
 	private static function __jsflash_encode(str:String):String{
-	
+
 		var x = str2blks(str);
 		var a =  1732584193;
 		var b = -271733879;
@@ -134,7 +139,7 @@ class Md5 {
 		var d =  271733878;
 
 		var step;
-		
+
 		var i = 0;
 		while( i < x.length )  {
 			var olda = a;
@@ -158,7 +163,7 @@ class Md5 {
 			a = ff(a, b, c, d, x[i+12], 7 ,  1804603682);
 			d = ff(d, a, b, c, x[i+13], 12, -40341101);
 			c = ff(c, d, a, b, x[i+14], 17, -1502002290);
-			b = ff(b, c, d, a, x[i+15], 22,  1236535329);    
+			b = ff(b, c, d, a, x[i+15], 22,  1236535329);
 			a = gg(a, b, c, d, x[i+ 1], 5 , -165796510);
 			d = gg(d, a, b, c, x[i+ 6], 9 , -1069501632);
 			c = gg(c, d, a, b, x[i+11], 14,  643717713);
@@ -217,8 +222,8 @@ class Md5 {
 		}
 		return rhex(a) + rhex(b) + rhex(c) + rhex(d);
 	}
-	
+
 	#end
 
-	
+
 }

std/Reflect.hx

@@ -23,6 +23,9 @@
  * DAMAGE.
  */
 
+/**
+	The different kind of basic types.
+**/
 enum BasicType {
 	TNull;
 	TInt;

std/String.hx

@@ -23,15 +23,32 @@
  * DAMAGE.
  */
 
+/**
+	The basic String class.
+**/
 extern class String {
 
+	/**
+		The number of characters in the String.
+	**/
 	property length(default,null) : Int;
 
 	function new(string:String) : Void;
 
+	/**
+		Returns an String where all characters have been uppercased.
+	**/
 	function toUpperCase() : String;
+
+	/**
+		Returns an String where all characters have been lowercased.
+	**/
 	function toLowerCase() : String;
 
+	/**
+		Returns the character at the given [index].
+		Returns the empty String if
+	**/
 	function charAt( index : Int) : String;
 	function charCodeAt( index : Int) : Int;
 

std/StringBuf.hx

@@ -23,8 +23,15 @@
  * DAMAGE.
  */
 
+/**
+	A String buffer is an efficient way to build a big string by
+	appending small elements together.
+**/
 class StringBuf {
 
+	/**
+		Creates a new string buffer.
+	**/
 	public function new() {
 		#if neko
 		b = __make();
@@ -36,6 +43,9 @@ class StringBuf {
 		#end
 	}
 
+	/**
+		Adds the representation of any value to the string buffer.
+	**/
 	public function add( x : Dynamic ) {
 		#if neko
 		__add(b,x);
@@ -47,6 +57,9 @@ class StringBuf {
 		#end
 	}
 
+	/**
+		Adds a part of a string to the string buffer.
+	**/
 	public function addSub( s : String, pos : Int, len : Int ) {
 		#if neko
 		__add_sub(b,untyped s.__s,pos,len);
@@ -58,6 +71,9 @@ class StringBuf {
 		#end
 	}
 
+	/**
+		Adds a character to the string buffer.
+	**/
 	public function addChar( c : Int ) {
 		#if neko
 		__add_char(b,c);
@@ -69,6 +85,10 @@ class StringBuf {
 		#end
 	}
 
+	/**
+		Returns the content of the string buffer.
+		The buffer is not emptied by this operation.
+	**/
 	public function toString() : String {
 		#if neko
 		return new String(__string(b));

std/StringTools.hx

@@ -23,8 +23,18 @@
  * DAMAGE.
  */
 
+
+/**
+	The StringTools class contains some extra functionalities for [String]
+	manipulation. It's stored in a different class in order to prevent
+	the standard [String] of being bloated and thus increasing the size of
+	each application using it.
+**/
 class StringTools {
 
+	/**
+		Encode an URL by using the standard format.
+	**/
 	public static function urlEncode( s : String ) : String {
 		#if flash
 		return untyped _global.escape(s);
@@ -36,6 +46,9 @@ class StringTools {
 		#end
 	}
 
+	/**
+		Decode an URL using the standard format.
+	**/
 	public static function urlDecode( s : String ) : String {
 		#if flash
 		return untyped _global.unescape(s);
@@ -47,29 +60,47 @@ class StringTools {
 		#end
 	}
 
-	public static function unhtml( s : String ) : String {
+	/**
+		Escape HTML special characters of the string.
+	**/
+	public static function htmlEscape( s : String ) : String {
 		return s.split("&").join("&amp;").split("<").join("&lt;").split(">").join("&gt;");
 	}
 
-	public static function rehtml( s : String ) : String {
+	/**
+		Unescape HTML special characters of the string.
+	**/
+	public static function htmlUnescape( s : String ) : String {
 		return s.split("&gt;").join(">").split("&lt;").join("<").split("&amp;").join("&");
 	}
 
+	/**
+		Tells if the string [s] starts with the string [start].
+	**/
 	public static function startsWith( s : String, start : String ) {
 		return( s.length >= start.length && s.substr(0,start.length) == start );
 	}
 
+	/**
+		Tells if the string [s] ends with the string [end].
+	**/
 	public static function endsWith( s : String, end : String ) {
 		var elen = end.length;
 		var slen = s.length;
 		return( slen >= elen && s.substr(slen-elen,elen) == end );
 	}
 
+	/**
+		Tells if the character in the string [s] at position [pos] is a space.
+	**/
 	public static function isSpace( s : String, pos : Int ) : Bool {
 		var c = s.charCodeAt( pos );
 		return (c >= 9 && c <= 13) || c == 32;
 	}
 
+	/**
+		Removes spaces at the left of the String [s].
+	**/
 	public static function ltrim( s : String ) : String {
 		var l = s.length;
 		var r = 0;
@@ -82,6 +113,9 @@ class StringTools {
 			return s;
 	}
 
+	/**
+		Removes spaces at the right of the String [s].
+	**/
 	public static function rtrim( s : String ) : String {
 		var l = s.length;
 		var r = 0;
@@ -95,10 +129,16 @@ class StringTools {
 		}
 	}
 
+	/**
+		Removes spaces at the beginning and the end of the String [s].
+	**/
 	public static function trim( s : String ) : String {
 		return ltrim(rtrim(s));
 	}
 
+	/**
+		Pad the string [s] by appending [c] at its right until it reach [l] characters.
+	**/
 	public static function rpad( s : String, c : String, l : Int ) : String {
 		var sl = s.length;
 		var cl = c.length;
@@ -114,6 +154,9 @@ class StringTools {
 		return s;
 	}
 
+	/**
+		Pad the string [s] by appending [c] at its left until it reach [l] characters.
+	**/
 	public static function lpad( s : String, c : String, l : Int ) : String {
 		var ns = "";
 		var sl = s.length;
@@ -132,6 +175,9 @@ class StringTools {
 		return ns+s;
 	}
 
+	/**
+		Replace all occurences of the string [sub] in the string [s] by the string [by].
+	**/
 	public static function replace( s : String, sub : String, by : String ) : String {
 		return s.split(sub).join(by);
 	}

std/Xml.hx

@@ -23,9 +23,18 @@
  * DAMAGE.
  */
 
+/**
+	An abstract type representing the type of the Xml
+	Node. You can compare it to [Xml] statics and can
+	use [Std.string(t)] to get a string reprensation
+	of the type.
+**/
 enum XmlType {
 }
 
+/**
+	Xml class and parsing.
+**/
 extern class Xml {
 
 	static property Element(default,null) : XmlType;