added List specification

std/Array.hx

@@ -62,7 +62,7 @@ extern class Array<T> {
 		[this] has exactly one element, the result is equal to a call to
 		Std.string(this[0]).
 		
-		If [a] is null, the result is unspecified.
+		If [sep] is null, the result is unspecified.
 	**/
 	function join( sep : String ) : String;
 
@@ -84,7 +84,7 @@ extern class Array<T> {
 		
 		This operation modifies [this] Array in place.
 		
-		[this].length will increase by 1.
+		[this].length increases by 1.
 	**/
 	function push(x : T) : Int;
 

std/List.hx

@@ -21,8 +21,8 @@
  */
 /**
 	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.
+	that are chained together. It is optimized so that adding or removing an
+	element does not imply copying the whole array content every time.
 **/
 class List<T> {
 
@@ -30,7 +30,7 @@ class List<T> {
 	private var q : Array<Dynamic>;
 
 	/**
-		The number of elements in this list.
+		The length of [this] List.
 	**/
 	public var length(default,null) : Int;
 
@@ -42,7 +42,9 @@ class List<T> {
 	}
 
 	/**
-		Add an element at the end of the list.
+		Adds element [item] at the end of [this] List.
+		
+		[this].length increases by 1.
 	**/
 	public function add( item : T ) {
 		var x:Array<Dynamic> = #if neko untyped __dollar__array(item,null) #else [item] #end;
@@ -55,7 +57,9 @@ class List<T> {
 	}
 
 	/**
-		Push an element at the beginning of the list.
+		Adds element [item] at the beginning of [this] List.
+		
+		[this].length increases by 1.
 	**/
 	public function push( item : T ) {
 		var x : Array<Dynamic> = #if neko
@@ -70,16 +74,18 @@ class List<T> {
 	}
 
 	/**
-		Returns the first element of the list, or null
-		if the list is empty.
+		Returns the first element of [this] List, or null if no elements exist.
+		
+		This function does not modify [this] List.
 	**/
 	public function first() : Null<T> {
 		return if( h == null ) null else h[0];
 	}
 
 	/**
-		Returns the last element of the list, or null
-		if the list is empty.
+		Returns the last element of [this] List, or null if no elements exist.
+		
+		This function does not modify [this] List.
 	**/
 	public function last() : Null<T> {
 		return if( q == null ) null else q[0];
@@ -87,9 +93,9 @@ class List<T> {
 
 
 	/**
-		Removes the first element of the list and
-		returns it or simply returns null if the
-		list is empty.
+		Returns the first element of [this] List, or null if no elements exist.
+		
+		The element is removed from [this] List.
 	**/
 	public function pop() : Null<T> {
 		if( h == null )
@@ -103,14 +109,17 @@ class List<T> {
 	}
 
 	/**
-		Tells if a list is empty.
+		Tells if [this] List is empty.
 	**/
 	public function isEmpty() : Bool {
 		return (h == null);
 	}
 
 	/**
-		Makes the list empty.
+		Empties [this] List.
+		
+		This function does not traverse the elements, but simply sets the
+		internal references to null and [this].length to 0.
 	**/
 	public function clear() : Void {
 		h = null;
@@ -119,8 +128,12 @@ class List<T> {
 	}
 
 	/**
-		Remove the first element that is [== v] from the list.
-		Returns [true] if an element was removed, [false] otherwise.
+		Removes the first occurence of [v] in [this] List.
+		
+		If [v] is found by checking standard equality, it is removed from [this]
+		List and the function returns true.
+		
+		Otherwise, false is returned.
 	**/
 	public function remove( v : T ) : Bool {
 		var prev = null;
@@ -182,7 +195,10 @@ class List<T> {
 	}
 
 	/**
-		Returns a displayable representation of the String.
+		Returns a string representation of [this] List.
+		
+		The result is enclosed in { } with the individual elements being
+		separated by a comma.
 	**/
 	public function toString() {
 		var s = new StringBuf();
@@ -202,7 +218,8 @@ class List<T> {
 	}
 
 	/**
-		Join the element of the list by using the separator [sep].
+		Returns a string representation of [this] List, with [sep] separating
+		each element.
 	**/
 	public function join(sep : String) {
 		var s = new StringBuf();
@@ -220,8 +237,8 @@ class List<T> {
 	}
 
 	/**
-		Returns a list filtered with [f]. The returned list
-		will contain all elements [x] for which [f(x) = true].
+		Returns a list filtered with [f]. The returned list will contain all
+		elements for which [f(x) = true].
 	**/
 	public function filter( f : T -> Bool ) {
 		var l2 = new List();
@@ -236,8 +253,8 @@ class List<T> {
 	}
 
 	/**
-		Returns a new list where all elements have been converted
-		by the function [f].
+		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();

tests/unit/unitstd/List.unit.hx

@@ -0,0 +1,40 @@
+var l = new List();
+l.toString() == "{}";
+l.isEmpty() == true;
+l.remove("1") == false;
+l.length == 0;
+l.first() == null;
+l.last() == null;
+l.pop() == null;
+l.add("1");
+l.length == 1;
+l.first() == "1";
+l.last() == "1";
+l.toString() == "{1}";
+l.isEmpty() == false;
+l.join("x") == "1";
+l.pop() == "1";
+l.remove("1") == false;
+l.length == 0;
+l.add("1");
+l.length == 1;
+l.remove("1") == true;
+l.add("1");
+l.push("2");
+l.length == 2;
+l.first() == "2";
+l.last() == "1";
+l.toString() == "{2, 1}";
+l.join("x") == "2x1";
+l.clear();
+l.isEmpty() == true;
+l.add("1");
+l.add("2");
+l.add("3");
+var l2 = l.map(function(i:String) return i + i);
+l2.pop() == "11";
+l2.pop() == "22";
+l2.pop() == "33";
+var l3 = l.filter(function(i:String) return i != "2");
+l3.pop() == "1";
+l3.pop() == "3";