[cpp] improve cpp.vm.Debugger docs + use new function type syntax

added backticks + switched to Haxe std style doc comments

std/cpp/vm/Debugger.hx

@@ -23,9 +23,9 @@
 package cpp.vm;
 
 /**
- * Parameter describes a function parameter.  Instances of this class are
- * embedded in stack frame objects to describe the function parameters that
- * were used in the invocation of the function that defines that stack frame.
+	Parameter describes a function parameter. Instances of this class are
+	embedded in stack frame objects to describe the function parameters that
+	were used in the invocation of the function that defines that stack frame.
 **/
 class Parameter {
 	public var name(default, null):String;
@@ -38,7 +38,7 @@ class Parameter {
 }
 
 /**
- * StackFrame describes one call stack frame.
+	`StackFrame` describes one call stack frame.
 **/
 class StackFrame {
 	public var fileName(default, null):String;
@@ -57,7 +57,7 @@ class StackFrame {
 }
 
 /**
- * ThreadInfo describes the state of a single thread.
+	`ThreadInfo` describes the state of a single thread.
 **/
 class ThreadInfo {
 	public static inline var STATUS_RUNNING = 1;
@@ -66,14 +66,18 @@ class ThreadInfo {
 	public static inline var STATUS_STOPPED_UNCAUGHT_EXCEPTION = 4;
 	public static inline var STATUS_STOPPED_CRITICAL_ERROR = 5;
 
-	// 0 is never a valid thread number
+	/** 0 is never a valid thread number **/
 	public var number(default, null):Int;
+
 	public var status(default, null):Int;
-	// If status is "stopped breakpoint", this is the breakpoint number
+
+	/** If status is "stopped breakpoint", this is the breakpoint number **/
 	public var breakpoint(default, null):Int;
-	// If status is "critical error", this describes the error
+
+	/** If status is "critical error", this describes the error **/
 	public var criticalErrorDescription(default, null):String;
-	// Stack will be listed with the lowest frame first
+
+	/** Stack will be listed with the lowest frame first **/
 	public var stack(default, null):Array<StackFrame>;
 
 	public function new(number:Int, status:Int, breakpoint:Int = -1, criticalErrorDescription:String = null) {
@@ -86,8 +90,8 @@ class ThreadInfo {
 }
 
 /**
- * This class wraps the hxcpp C++ implementation to provide a Haxe interface
- * to the low level debugging features
+	This class wraps the hxcpp C++ implementation to provide a Haxe interface
+	to the low level debugging features
 **/
 class Debugger {
 	public static inline var THREAD_CREATED = 1;
@@ -99,143 +103,149 @@ class Debugger {
 	public static inline var STEP_OVER = 2;
 	public static inline var STEP_OUT = 3;
 
-	// This tagging value is returned by getStackVariableValue() and
-	// setStackVariableValue if the requested value does not exist at the
-	// requested stack frame
-	public static var NONEXISTENT_VALUE = new String("NONEXISTENT_VALUE");
-	// This tagging value is returned by getStackVariableValue and
-	// setStackVariableValue if the stack variable that is being set is on a
-	// thread that is running, in which case the set does not take place.
-	public static var THREAD_NOT_STOPPED = new String("THREAD_NOT_STOPPED");
+	/**
+		This tagging value is returned by `getStackVariableValue()` and
+		`setStackVariableValue()` if the requested value does not exist at the
+		requested stack frame
+	**/
+	public static var NONEXISTENT_VALUE = "NONEXISTENT_VALUE";
+
+	/**
+		This tagging value is returned by `getStackVariableValue()` and
+		`setStackVariableValue()` if the stack variable that is being set is on a
+		thread that is running, in which case the set does not take place.
+	**/
+	public static var THREAD_NOT_STOPPED = "THREAD_NOT_STOPPED";
 
 	/**
-	 * Sets the handler callback to be made when asynchronous events occur,
-	 * specifically, when threads are created, terminated, started, or
-	 * stopped.  The calling thread becomes the "debugger" thread, which means
-	 * that it will be discluded from any breakpoints and will not be reported
-	 * on by any thread reporting requests.
-	 *
-	 * Be aware that this callback is made asynchronously and possibly by
-	 * multiple threads simultaneously.
-	 *
-	 * Setting this to null prevents further callbacks.
-	 *
-	 * Throws a string exception if the program does not support debugging
-	 * because it was not compiled with the HXCPP_DEBUGGER flag set.
-	 *
-	 * @param handler is a function that will be called back by asynchronous
-	 *        thread events.  Note that this function is called directly from
-	 *        the thread experiencing the event and the handler should return
-	 *        quickly to avoid blocking the calling thread unnecessarily.
-	 *        The parameters to handler are:
-	 *          - threadNumber, the thread number of the event
-	 *          - event, one of THREAD_CREATED, THREAD_TERMINATED,
-	 *            THREAD_STARTED, or THREAD_STOPPED
-	 *          - stackFrame, the stack frame number at which the thread is stopped,
-	 *            undefined if event is not THREAD_STOPPED
-	 *          - className, the class name at which the thread is stopped,
-	 *            undefined if event is not THREAD_STOPPED
-	 *          - functionName, the function name at which the thread is
-	 *            stopped, undefined if event is not THREAD_STOPPED
-	 *          - fileName, the file name at which the thread is stopped,
-	 *            undefined if event is not THREAD_STOPPED
-	 *          - lineNumber, the line number at which the thread is stopped,
-	 *            undefined if event is not THREAD_STOPPED
+		Sets the handler callback to be made when asynchronous events occur,
+		specifically, when threads are created, terminated, started, or
+		stopped. The calling thread becomes the "debugger" thread, which means
+		that it will be discluded from any breakpoints and will not be reported
+		on by any thread reporting requests.
+
+		Be aware that this callback is made asynchronously and possibly by
+		multiple threads simultaneously.
+
+		Setting this to `null` prevents further callbacks.
+
+		Throws a string exception if the program does not support debugging
+		because it was not compiled with the `HXCPP_DEBUGGER` flag set.
+
+		@param handler is a function that will be called back by asynchronous
+			   thread events.  Note that this function is called directly from
+			   the thread experiencing the event and the handler should return
+			   quickly to avoid blocking the calling thread unnecessarily.
+			   The parameters to handler are:
+				 - `threadNumber`, the thread number of the event
+				 - event, one of `THREAD_CREATED`, `THREAD_TERMINATED`,
+				   `THREAD_STARTED`, or `THREAD_STOPPED`
+				 - stackFrame, the stack frame number at which the thread is stopped,
+				   undefined if event is not `THREAD_STOPPED`
+				 - `className`, the class name at which the thread is stopped,
+				   undefined if event is not `THREAD_STOPPED`
+				 - `functionName`, the function name at which the thread is
+				   stopped, undefined if event is not `THREAD_STOPPED`
+				 - `fileName`, the file name at which the thread is stopped,
+				   undefined if event is not `THREAD_STOPPED`
+				 - `lineNumber`, the line number at which the thread is stopped,
+				   undefined if event is not `THREAD_STOPPED`
 	**/
-	public static function setEventNotificationHandler(handler:Int->Int->Int->String->String->String->Int->Void) {
+	public static function setEventNotificationHandler(handler:(threadNumber:Int, event:Int, stackFrame:Int, className:String, functionName:String,
+		fileName:String, lineNumber:Int) -> Void) {
 		untyped __global__.__hxcpp_dbg_setEventNotificationHandler(handler);
 	}
 
 	/**
-	 * This can be called to turn off (and then back on) all stopping of
-	 * debugged threads temporarily.  It should only be used by classes that
-	 * actually implement the debugger to hide themselves from the debugger as
-	 * necessary.
+		This can be called to turn off (and then back on) all stopping of
+		debugged threads temporarily. It should only be used by classes that
+		actually implement the debugger to hide themselves from the debugger as
+		necessary.
 	**/
 	public static function enableCurrentThreadDebugging(enabled:Bool) {
 		untyped __global__.__hxcpp_dbg_enableCurrentThreadDebugging(enabled);
 	}
 
 	/**
-	 * Returns the thread number of the calling thread.
-	 *
-	 * @return the thread number of the calling thread.
+		Returns the thread number of the calling thread.
+
+		@return the thread number of the calling thread.
 	**/
 	public static function getCurrentThreadNumber():Int {
 		return untyped __global__.__hxcpp_dbg_getCurrentThreadNumber();
 	}
 
 	/**
-	 * Returns the set of source files known to the debugger.  This is a copy
-	 * of the original array and could be quite large.  The caller should
-	 * cache this value to avoid multiple copies needing to be made.
-	 *
-	 * @return the set of source files known to the debugger.
+		Returns the set of source files known to the debugger. This is a copy
+		of the original array and could be quite large. The caller should
+		cache this value to avoid multiple copies needing to be made.
+
+		@return the set of source files known to the debugger.
 	**/
 	public static function getFiles():Array<String> {
 		return untyped __global__.__hxcpp_dbg_getFiles();
 	}
 
 	/**
-	 * Returns the full paths of the set of source files known to the debugger.
-	 * This is a copy of the original array and could be quite large.
-	 * It is possible that this set will be empty, in which case the full paths are not known.
-	 * The index of these files matches the index from "getFiles", so the full path for
-	 * a given short path can be calculated.
-	 *
-	 * @return the known full paths of the set of source files
+		Returns the full paths of the set of source files known to the debugger.
+		This is a copy of the original array and could be quite large.
+		It is possible that this set will be empty, in which case the full paths are not known.
+		The index of these files matches the index from `getFiles()`, so the full path for
+		a given short path can be calculated.
+
+		@return the known full paths of the set of source files
 	**/
 	public static function getFilesFullPath():Array<String> {
 		return untyped __global__.__hxcpp_dbg_getFilesFullPath();
 	}
 
 	/**
-	 * Returns the set of class names of all classes known to the debugger.
-	 * This is a copy of the original array and could be quite large.  The
-	 * caller should cache this value to avoid multiple copies needing to be
-	 * made.
-	 *
-	 * @return the set of class names of all classes known to the debugger.
+		Returns the set of class names of all classes known to the debugger.
+		This is a copy of the original array and could be quite large. The
+		caller should cache this value to avoid multiple copies needing to be
+		made.
+
+		@return the set of class names of all classes known to the debugger.
 	**/
 	public static function getClasses():Array<String> {
 		return untyped __global__.__hxcpp_dbg_getClasses();
 	}
 
 	/**
-	 * Returns a ThreadInfo object describing every thread that existed at the
-	 * moment that the call was made, except for the debugger thread.
+		Returns a `ThreadInfo` object describing every thread that existed at the
+		moment that the call was made, except for the debugger thread.
 	**/
 	public static function getThreadInfos():Array<ThreadInfo> {
 		return untyped __global__.__hxcpp_dbg_getThreadInfos();
 	}
 
 	/**
-	 * Returns a ThreadInfo object describing a single thread, or null if
-	 * there is no such thread or the thread queried about was the debugger
-	 * thread and unsafe was not true.
+		Returns a `ThreadInfo` object describing a single thread, or `null` if
+		there is no such thread or the thread queried about was the debugger
+		thread and `unsafe` was not `true`.
 	**/
 	public static function getThreadInfo(threadNumber:Int, unsafe:Bool):ThreadInfo {
 		return untyped __global__.__hxcpp_dbg_getThreadInfo(threadNumber, unsafe);
 	}
 
 	/**
-	 * Adds a new file:line breakpoint.  The breakpoint number of the newly
-	 * added breakpoint is returned.
+		Adds a new `file:line` breakpoint. The breakpoint number of the newly
+		added breakpoint is returned.
 	**/
 	public static function addFileLineBreakpoint(file:String, line:Int):Int {
 		return untyped __global__.__hxcpp_dbg_addFileLineBreakpoint(file, line);
 	}
 
 	/**
-	 * Adds a new class:function breakpoint.  The breakpoint number of the
-	 * newly added breakpoint is returned.
+		Adds a new `class:function` breakpoint. The breakpoint number of the
+		newly added breakpoint is returned.
 	**/
 	public static function addClassFunctionBreakpoint(className:String, functionName:String):Int {
 		return untyped __global__.__hxcpp_dbg_addClassFunctionBreakpoint(className, functionName);
 	}
 
 	/**
-	 * Deletes a breakpoint, or all breakpoints.
+		Deletes a breakpoint, or all breakpoints.
 	**/
 	public static function deleteBreakpoint(number:Null<Int>) {
 		if (number == null) {
@@ -246,65 +256,65 @@ class Debugger {
 	}
 
 	/**
-	 * Breaks all threads except the debugger thread (which should be the same
-	 * as the calling thread!).
-	 *
-	 * If `wait` is true, waits up to 2 seconds for all threads to be broken.
-	 * Threads which are in blocking system calls and cannot break after 2
-	 * seconds remain running when this function returns.
+		Breaks all threads except the debugger thread (which should be the same
+		as the calling thread!).
+
+		If `wait` is `true`, waits up to 2 seconds for all threads to be broken.
+		Threads which are in blocking system calls and cannot break after 2
+		seconds remain running when this function returns.
 	**/
 	public static function breakNow(wait:Bool = true) {
 		untyped __global__.__hxcpp_dbg_breakNow(wait);
 	}
 
 	/**
-	 * Continue execution of all stopped threads.  If specialThreadNumber
-	 * is a valid thread number, then it will be continued past
-	 * `continueCount` breakpoints instead of just 1 like all of the other
-	 * threads.
+		Continue execution of all stopped threads. If `specialThreadNumber`
+		is a valid thread number, then it will be continued past
+		`continueCount` breakpoints instead of just 1 like all of the other
+		threads.
 	**/
 	public static function continueThreads(specialThreadNumber:Int, continueCount:Int) {
 		untyped __global__.__hxcpp_dbg_continueThreads(specialThreadNumber, continueCount);
 	}
 
 	/**
-	 * Single steps the given thread.
+		Single steps the given thread.
 	**/
 	public static function stepThread(threadNumber:Int, stepType:Int, stepCount:Int = 1) {
 		untyped __global__.__hxcpp_dbg_stepThread(threadNumber, stepType, stepCount);
 	}
 
 	/**
-	 * Returns the list of local variables (including "this", function
-	 * arguments, and local variables) visible to the given thread at the
-	 * given stack frame.
-	 *
-	 * Returns a list with a single entry, THREAD_NOT_STOPPED, if the
-	 * thread is not stopped and thus variables cannot be fetched and
-	 * unsafe is not true.
-	 *
-	 * @return the list of local variables (including "this", function
-	 *         arguments, and local variables) visible to the given thread at
-	 *         the given stack frame.
+		Returns the list of local variables (including `this`, function
+		arguments, and local variables) visible to the given thread at the
+		given stack frame.
+
+		Returns a list with a single entry, `THREAD_NOT_STOPPED`, if the
+		thread is not stopped and thus variables cannot be fetched and
+		`unsafe` is not `true`.
+
+		@return the list of local variables (including `this`, function
+				arguments, and local variables) visible to the given thread at
+				the given stack frame.
 	**/
 	public static function getStackVariables(threadNumber:Int, stackFrameNumber:Int, unsafe:Bool):Array<String> {
 		return untyped __global__.__hxcpp_dbg_getStackVariables(threadNumber, stackFrameNumber, unsafe, THREAD_NOT_STOPPED);
 	}
 
 	/**
-	 * Returns the value of a stack variable, or NONEXISTENT_VALUE if the
-	 * requested value does not exist.  If the thread is actively running
-	 * and unsafe is not true, returns THREAD_NOT_STOPPED.
+		Returns the value of a stack variable, or `NONEXISTENT_VALUE` if the
+		requested value does not exist.  If the thread is actively running
+		and `unsafe` is not `true`, returns `THREAD_NOT_STOPPED`.
 	**/
 	public static function getStackVariableValue(threadNumber:Int, stackFrameNumber:Int, name:String, unsafe:Bool):Dynamic {
 		return untyped __global__.__hxcpp_dbg_getStackVariableValue(threadNumber, stackFrameNumber, name, unsafe, NONEXISTENT_VALUE, THREAD_NOT_STOPPED);
 	}
 
 	/**
-	 * Sets the value of a stack variable and returns that value.  If the
-	 * variable does not exist, on the stack, this function returns
-	 * NONEXISTENT_VALUE.  If the thread is actively running and unsafe is not
-	 * true, returns THREAD_NOT_STOPPED, and the value is not set.
+		Sets the value of a stack variable and returns that value. If the
+		variable does not exist, on the stack, this function returns
+		`NONEXISTENT_VALUE`. If the thread is actively running and `unsafe` is not
+		`true`, returns `THREAD_NOT_STOPPED`, and the value is not set.
 	**/
 	public static function setStackVariableValue(threadNumber:Int, stackFrameNumber:Int, name:String, value:Dynamic, unsafe:Bool):Dynamic {
 		return untyped __global__.__hxcpp_dbg_setStackVariableValue(threadNumber, stackFrameNumber, name, value, unsafe, NONEXISTENT_VALUE,