added StringBuf specification

std/Class.hx

@@ -21,6 +21,7 @@
  */
 /**
 	An abstract type that represents a Class.
+	
 	See [Type] for the haXe Reflection API.
 **/
 @:runtimeValue abstract Class<T> {

std/Enum.hx

@@ -21,7 +21,10 @@
  */
 
 /**
-	An abstract type that represents an Enum.
+	An abstract type that represents an Enum type.
+	
+	The corresponding enum instance type is EnumValue.
+	
 	See [Type] for the haXe Reflection API.
 **/
 @:runtimeValue abstract Enum<T> {

std/StringBuf.hx

@@ -20,41 +20,69 @@
  * DEALINGS IN THE SOFTWARE.
  */
 /**
-	A String buffer is an efficient way to build a big string by
-	appending small elements together.
+	A String buffer is an efficient way to build a big string by appending small
+	elements together.
+	
+	Its cross-platform implementation uses String concatenation internally, but
+	StringBuf may be optimized for different targets.
+	
+	Unlike String, an instance of StringBuf is not immutable in the sense that
+	it can be passed as argument to functions which modify it by appending more
+	values. However, the internal buffer cannot be modified.
 **/
 class StringBuf {
 
 	var b:String = "";
 	
 	/**
-		Creates a new string buffer.
+		Creates a new StringBuf instance.
+		
+		This may involve initialization of the internal buffer.
 	**/
 	public function new() {}
 
 	/**
-		Adds the representation of any value to the string buffer.
+		Appends the representation of [x] to [this] StringBuf.
+		
+		The exact representation of [x] may vary per platform. To get more
+		consistent behavior, this function should be called with
+		Std.string(x).
+		
+		If [x] is null, the String "null" is appended.
 	**/
 	public inline function add( x : Dynamic ) : Void {
 		b += x;
 	}
 
 	/**
-		Adds a part of a string to the string buffer.
+		Appends the character identified by [c] to [this] StringBuf.
+		
+		If [c] is negative or has another invalid value, the result is
+		unspecified.
 	**/
 	public inline function addChar( c : Int ) : Void {
 		b += String.fromCharCode(c);
 	}
 
 	/**
-		Adds a character to the string buffer.
+		Appends a substring of [s] to [this] StringBuf.
+		
+		This function expects [pos] and [len] to describe a valid substring of
+		[s], or else the result is unspecified. To get more robust behavior,
+		[this].add(s.substr(pos,len)) can be used instead.
+		
+		If [s] or [pos] are null, the result is unspecified.
+		
+		If [len] is omitted or null, the substring ranges from [pos] to the end
+		of [s].
 	**/
 	public inline function addSub( s : String, pos : Int, ?len : Int) : Void {
 		b += s.substr(pos, len);
 	}
 
 	/**
-		Returns the content of the string buffer.
+		Returns the content of [this] StringBuf as String.
+		
 		The buffer is not emptied by this operation.
 	**/
 	public inline function toString() : String {

std/haxe/PosInfos.hx

@@ -21,10 +21,21 @@
  */
 package haxe;
 
+/**
+	PosInfos is a magic type which can be used to generate some position
+	information into the output for debugging use.
+	
+	If a function has a final optional argument of this type, i.e.
+	(...,?pos:haxe.PosInfos), each call to that function which does not assign
+	a value to that argument has its position added as call argument.
+	
+	This can be used to track positions of calls in e.g. a unit testing
+	framework.
+**/
 typedef PosInfos = {
 	var fileName : String;
 	var lineNumber : Int;
 	var className : String;
 	var methodName : String;
 	@:optional var customParams : Array<Dynamic>;
-}
+}

tests/unit/unitstd/StringBuf.unit.hx

@@ -0,0 +1,27 @@
+// add, toString
+var x = new StringBuf();
+x.toString() == "";
+x.add(null);
+x.toString() == "null";
+
+// addChar
+var x = new StringBuf();
+x.addChar(32);
+x.toString() == " ";
+
+// addSub
+var x = new StringBuf();
+x.addSub("abcdefg", 1);
+x.toString() == "bcdefg";
+var x = new StringBuf();
+x.addSub("abcdefg", 1, null);
+x.toString() == "bcdefg";
+var x = new StringBuf();
+x.addSub("abcdefg", 1, 3);
+x.toString() == "bcd";
+
+// identity
+function identityTest(s:StringBuf) {
+	return s;
+}
+identityTest(x) == x;