haxe.unit documentation (#5404)

* haxe.unit documentation

* Update TestCase.hx

* Update TestCase.hx

Test function doesnt need to be public

* Update TestRunner.hx

Dynamic function note

std/haxe/unit/TestCase.hx

@@ -22,17 +22,52 @@
 package haxe.unit;
 import haxe.PosInfos;
 
+/**
+	This unit test class should be extended to create test cases. Each test 
+	method created in this extended class should start with the name "test".
+
+	These test methods should call the assertion methods:
+
+	 * `assertTrue(a)`: Succeeds if `a` is `true`.
+	 * `assertFalse(a)`: Succeeds if `a` is `false`.
+	 * `assertEquals(expected, actual)`: Succeeds if `expected` and `actual`
+	   are equal.
+
+	```haxe
+	class MyTestCase extends haxe.unit.TestCase {
+		function testBasic() {
+			assertEquals("A", "A");
+		}
+	}
+	```
+
+	The TestCase can be tested using `TestRunner`. 
+
+	To run code before or after the test, override the functions `setup` 
+	and `tearDown`.
+
+	@see <http://haxe.org/manual/std-unit-testing.html>
+**/
 @:keepSub
 @:publicFields
 class TestCase {
+	/**
+		The current test status of the TestRunner.
+	**/
 	public var currentTest : TestStatus;
 
 	public function new( ) {
 	}
 
+	/**
+		Override this method to execute code before the test runs.
+	**/
 	public function setup() : Void {
 	}
 
+	/**
+		Override this method to execute code after the test ran.
+	**/
 	public function tearDown() : Void {
 	}
 
@@ -40,6 +75,9 @@ class TestCase {
 		haxe.unit.TestRunner.print(v);
 	}
 
+	/**
+		Succeeds if `b` is `true`.
+	**/
 	function assertTrue( b:Bool, ?c : PosInfos ) : Void {
 		currentTest.done = true;
 		if (b != true){
@@ -50,6 +88,9 @@ class TestCase {
 		}
 	}
 
+	/**
+		Succeeds if `b` is `false`.
+	**/
 	function assertFalse( b:Bool, ?c : PosInfos ) : Void {
 		currentTest.done = true;
 		if (b == true){
@@ -60,7 +101,10 @@ class TestCase {
 		}
 	}
 
-	function assertEquals<T>( expected: T , actual: T,  ?c : PosInfos ) : Void 	{
+	/**
+		Succeeds if `expected` and `actual` are equal.
+	**/
+	function assertEquals<T>( expected: T , actual: T,  ?c : PosInfos ) : Void {
 		currentTest.done = true;
 		if (actual != expected){
 			currentTest.success = false;
@@ -69,5 +113,4 @@ class TestCase {
 			throw currentTest;
 		}
 	}
-
 }

std/haxe/unit/TestResult.hx

@@ -21,10 +21,16 @@
  */
  package haxe.unit;
 
+/**
+	TestResult contains the result of the executed unit tests.
+**/
 class TestResult {
-
 	var m_tests : List<TestStatus>;
-	public var success(default,null) : Bool;
+
+	/**
+		`true` if the unit test succesfully executed the test cases.
+	**/
+	public var success(default, null) : Bool;
 
 	public function new() {
 		m_tests = new List();
@@ -37,6 +43,9 @@ class TestResult {
 			success = false;
 	}
 
+	/**
+		String representation from the result of the unit test.
+	**/
 	public function toString() : String 	{
 		var buf = new StringBuf();
 		var failures = 0;

std/haxe/unit/TestRunner.hx

@@ -22,14 +22,41 @@
 package haxe.unit;
 import Reflect;
 
+/**
+	This class runs unit test cases and prints the result.
+	
+	```haxe
+	var r = new haxe.unit.TestRunner();
+	r.add(new MyTestCase());
+	// add other TestCases here
+	
+	// finally, run the tests
+	r.run();
+	```
+	
+	@see <http://haxe.org/manual/std-unit-testing.html>
+**/
 class TestRunner {
+	/**
+		The unit test results. Available after the `run()` is called.
+	**/
 	public var result(default, null) : TestResult;
+
 	var cases  : List<TestCase>;
 
 #if flash
 	static var tf : flash.text.TextField = null;
 #end
 
+	/**
+		Prints the given object/value.
+		
+		 * Flash outputs the result in a new `TextField` on stage.
+		 * JavaScript outputs the result using `console.log`.
+		 * Other targets use native `print` to output the result.
+
+		This function is `dynamic` so it can be overriden in custom setups.
+	**/
 	public static dynamic function print( v : Dynamic ) untyped {
 		#if flash
 			if( tf == null ) {
@@ -49,11 +76,11 @@ class TestRunner {
 		#elseif js
 			var msg = js.Boot.__string_rec(v,"");
 			var d;
-            if( __js__("typeof")(document) != "undefined"
-                    && (d = document.getElementById("haxe:trace")) != null ) {
-                msg = StringTools.htmlEscape(msg).split("\n").join("<br/>");
-                d.innerHTML += msg+"<br/>";
-            }
+			if( __js__("typeof")(document) != "undefined"
+				&& (d = document.getElementById("haxe:trace")) != null ) {
+				msg = StringTools.htmlEscape(msg).split("\n").join("<br/>");
+				d.innerHTML += msg+"<br/>";
+			}
 			else if (  __js__("typeof process") != "undefined"
 					&& __js__("process").stdout != null
 					&& __js__("process").stdout.write != null)
@@ -83,10 +110,18 @@ class TestRunner {
 		cases = new List();
 	}
 
+	/**
+		Add TestCase instances to the unit test.
+	**/
 	public function add( c:TestCase ) : Void{
 		cases.add(c);
 	}
 
+	/**
+		Runs the unit tests and prints the results.
+		
+		@return `true` if the unit test succesfully executed the test cases.
+	**/
 	public function run() : Bool {
 		result = new TestResult();
 		for ( c in cases ){

std/haxe/unit/TestStatus.hx

@@ -24,18 +24,49 @@ import haxe.CallStack;
 
 import haxe.PosInfos;
 
+/**
+	The status information of a unit test case method.
+
+	@see <http://haxe.org/manual/std-unit-testing.html>
+**/
 class TestStatus {
+	/**
+		`true` when the unit test is executed.
+	**/
 	public var done : Bool;
+
+	/**
+		`true` when succesfully unit tested.
+	**/
 	public var success : Bool;
+
+	/**
+		The error message of the unit test method.
+	**/
 	public var error : String;
+
+	/**
+		The method name of the unit test.
+	**/
 	public var method : String;
+
+	/**
+		The class name of the unit test.
+	**/
 	public var classname : String;
+
+	/**
+		The position information of the unit test.
+	**/
 	public var posInfos : PosInfos;
+
+	/**
+		The representation of the stack exception.
+	**/
 	public var backtrace : String;
 
 	public function new() 	{
 		done = false;
 		success = false;
 	}
-
 }