Updated array docs

std/Array.hx

@@ -21,13 +21,13 @@
  */
 /**
 	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
+	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 [this] Array.
+		The length of `this` Array.
 	**/
 	var length(default,null) : Int;
 
@@ -37,140 +37,140 @@ extern class Array<T> {
 	function new() : Void;
 
 	/**
-		Returns a new Array by appending the elements of [a] to the elements of
-		[this] Array.
+		Returns a new Array by appending the elements of `a` to the elements of
+		`this` Array.
 		
-		This operation does not modify [this] Array.
+		This operation does not modify `this` Array.
 		
-		If [a] is the empty Array [], a copy of [this] Array is returned.
+		If `a` is the empty Array `[]`, a copy of `this` Array is returned.
 		
-		The length of the returned Array is equal to the sum of [this].length
-		and [a].length.
+		The length of the returned Array is equal to the sum of `this.length` 
+		and `a.length`.
 		
-		If [a] is null, the result is unspecified.
+		If `a` is `null`, the result is unspecified.
 	**/
 	function concat( a : Array<T> ) : Array<T>;
 
 	/**
-		Returns a string representation of [this] Array, with [sep] separating
+		Returns a string representation of `this` Array, with `sep` separating
 		each element.
 		
-		The result of this operation is equal to Std.string(this[0]) + sep +
-		Std.string(this[1]) + sep + ... + sep + Std.string(this[this.length-1]).
+		The result of this operation is equal to `Std.string(this[0]) + sep +
+		Std.string(this[1]) + sep + ... + sep + Std.string(this[this.length-1])`
 		
-		If [this] is the empty Array [], the result is the empty String "". If
-		[this] has exactly one element, the result is equal to a call to
-		Std.string(this[0]).
+		If `this` is the empty Array `[]`, the result is the empty String `""`. 
+		If `this` has exactly one element, the result is equal to a call to
+		`Std.string(this[0])`.
 		
-		If [sep] is null, the result is unspecified.
+		If `sep` is null, the result is unspecified.
 	**/
 	function join( sep : String ) : String;
 
 	/**
-		Removes the last element of [this] Array and returns it.
+		Removes the last element of `this` Array and returns it.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
-		If [this] has at least one element, [this].length will decrease by 1.
+		If `this` has at least one element, `this.length` will decrease by 1.
 		
-		If [this] is the empty Array [], null is returned and the length remains
-		0.
+		If `this` is the empty Array `[]`, null is returned and the length 
+		remains 0.
 	**/
 	function pop() : Null<T>;
 
 	/**
-		Adds the element [x] at the end of [this] Array and returns the offset
+		Adds the element `x` at the end of `this` Array and returns the offset
 		it was added at.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
-		[this].length increases by 1.
+		`this.length` increases by 1.
 	**/
 	function push(x : T) : Int;
 
 	/**
-		Reverse the order of elements of [this] Array.
+		Reverse the order of elements of `this` Array.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
-		If [this].length < 2, [this] remains unchanged.
+		If `this.length < 2`, `this` remains unchanged.
 	**/
 	function reverse() : Void;
 
 	/**
-		Removes the first element of [this] Array and returns it.
+		Removes the first element of `this` Array and returns it.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
-		If [this] has at least one element, [this].length and the index of each
+		If `this` has at least one element, `this`.length and the index of each
 		remaining element is decreased by 1.
 		
-		If [this] is the empty Array [], null is returned and the length remains
-		0.
+		If `this` is the empty Array `[]`, `null` is returned and the length 
+		remains 0.
 	**/
 	function shift() : Null<T>;
 
 	/**
-		Creates a shallow copy of the range of [this] Array, starting at and
-		including [pos], up to but not including [end].
+		Creates a shallow copy of the range of `this` Array, starting at and
+		including `pos`, up to but not including `end`.
 		
-		This operation does not modify [this] Array.
+		This operation does not modify `this` Array.
 		
 		The elements are not copied and retain their identity.
 		
-		If [end] is omitted or exceeds [this].length, it defaults to the end of
-		[this] Array.
+		If `end` is omitted or exceeds `this.length`, it defaults to the end of
+		`this` Array.
 		
-		If [pos] or [end] are negative, their offsets are calculated from the
-		end	of [this] Array by [this].length + [pos] and [this].length + [end]
+		If `pos` or `end` are negative, their offsets are calculated from the
+		end	of `this` Array by `this.length + pos` and `this.length + end`
 		respectively. If this yields a negative value, 0 is used instead.
 		
-		If [pos] exceeds [this].length or if [end} exceeds or equals [pos],
-		the result is [].
+		If `pos` exceeds `this.length` or if `end` exceeds or equals `pos`,
+		the result is `[]`.
 	**/
 	function slice( pos : Int, ?end : Int ) : Array<T>;
 
 	/**
-		Sorts [this] Array according to the comparison function [f], where
-		[f(x,y)] returns 0 if x == y, a positive Int if x > y and a
+		Sorts `this` Array according to the comparison function `f`, where
+		`f(x,y)` returns 0 if x == y, a positive Int if x > y and a
 		negative Int if x < y.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
 		The sort operation is not guaranteed to be stable, which means that the
 		order of equal elements may not be retained. For a stable Array sorting
-		algorithm, haxe.ds.sort.MergeSort.sort() can be used instead.
+		algorithm, `haxe.ds.sort.MergeSort.sort()` can be used instead.
 		
-		If [f] is null, the result is unspecified.
+		If `f` is null, the result is unspecified.
 	**/
 	function sort( f : T -> T -> Int ) : Void;
 
 	/**
-		Removes [len] elements from [this] Array, starting at and including
-		[pos], an returns them.
+		Removes `len` elements from `this` Array, starting at and including
+		`pos`, an returns them.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
-		If [len] is < 0 or [pos] exceeds [this].length, the result is the empty
+		If `len` is < 0 or `pos` exceeds `this`.length, the result is the empty
 		Array [].
 		
-		If [pos] is negative, its value is calculated from the end	of [this]
-		Array by [this].length + [pos]. If this yields a negative value, 0 is
+		If `pos` is negative, its value is calculated from the end	of `this`
+		Array by `this.length + pos`. If this yields a negative value, 0 is
 		used instead.
 		
-		If the sum of the resulting values for [len] and [pos] exceed
-		[this].length, this operation will affect the elements from [pos] to the
-		end of [this] Array.
+		If the sum of the resulting values for `len` and `pos` exceed
+		`this.length`, this operation will affect the elements from `pos` to the
+		end of `this` Array.
 		
-		The length of the returned Array is equal to the new length of [this]
-		Array subtracted from the original length of [this] Array. In other
-		words, each element of the original [this] Array either remains in
-		[this] Array or becomes an element of the returned Array.
+		The length of the returned Array is equal to the new length of `this`
+		Array subtracted from the original length of `this` Array. In other
+		words, each element of the original `this` Array either remains in
+		`this` Array or becomes an element of the returned Array.
 	**/
 	function splice( pos : Int, len : Int ) : Array<T>;
 
 	/**
-		Returns a string representation of [this] Array.
+		Returns a string representation of `this` Array.
 		
 		The result will include the individual elements' String representations
 		separated by comma. The enclosing [ ] may be missing on some platforms,
@@ -180,53 +180,53 @@ extern class Array<T> {
 	function toString() : String;
 
 	/**
-		Adds the element [x] at the start of [this] Array.
+		Adds the element `x` at the start of `this` Array.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
-		[this].length and the index of each Array element increases by 1.
+		`this.length` and the index of each Array element increases by 1.
 	**/
 	function unshift( x : T ) : Void;
 
 	/**
-		Inserts the element [x] at the position [pos].
+		Inserts the element `x` at the position `pos`.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
 		The offset is calculated like so:
 			
-		- If [pos] exceeds [this].length, the offset is [this].length.
-		- If [pos] is negative, the offset is calculated from the end of [this]
-		Array, i.e. [this].length + [pos]. If this yields a negative value,
-		the offset is 0.
-		- Otherwise, the offset is [pos].
-		
-		If the resulting offset does not exceed [this].length, all elements from
-		and including that offset to the end of [this] Array are moved one index
+		- If `pos` exceeds `this.length`, the offset is `this.length`.
+		- If `pos` is negative, the offset is calculated from the end of `this` 
+		  Array, i.e. `this.length + pos`. If this yields a negative value, the 
+		  offset is 0.
+		- Otherwise, the offset is `pos`.
+		
+		If the resulting offset does not exceed `this.length`, all elements from
+		and including that offset to the end of `this` Array are moved one index
 		ahead.
 	**/
 	function insert( pos : Int, x : T ) : Void;
 
 	/**
-		Removes the first occurence of [x] in [this] Array.
+		Removes the first occurence of `x` in `this` Array.
 		
-		This operation modifies [this] Array in place.
+		This operation modifies `this` Array in place.
 		
-		If [x] is found by checking standard equality, it is removed from [this]
+		If `x` is found by checking standard equality, it is removed from `this`
 		Array and all following elements are reindexed acoordingly. The function
 		then returns true.
 		
-		If [x] is not found, [this] Array is not changed and the function
+		If `x` is not found, `this` Array is not changed and the function
 		returns false.
 	**/
 	function remove( x : T ) : Bool;
 
 	/**
-		Returns a shallow copy of [this] Array.
+		Returns a shallow copy of `this` Array.
 		
 		The elements are not copied and retain their identity, so
-		a[i] == a.copy()[i] is true for any valid i. However, a == a.copy() is
-		always false.
+		`a[i] == a.copy()[i]` is true for any valid `i`. However, 
+		`a == a.copy()` is always false.
 	**/
 	function copy() : Array<T>;