COMMON: Cleaned up coroutine comments

2 files changed, 38 insertions, 24 deletions

diff --git a/common/coroutines.cpp b/common/coroutines.cpp
index aff13a5494..b1b08c6bae 100644
--- a/common/coroutines.cpp
+++ b/common/coroutines.cpp
@@ -37,11 +37,15 @@ DECLARE_SINGLETON(CoroutineScheduler);
 
 #ifdef COROUTINE_DEBUG
 namespace {
+/** Count of active coroutines */
 static int s_coroCount = 0;
 
 typedef Common::HashMap<Common::String, int> CoroHashMap;
 static CoroHashMap *s_coroFuncs = 0;
 
+/**
+ * Change the current coroutine status
+ */
 static void changeCoroStats(const char *func, int change) {
 	if (!s_coroFuncs)
 		s_coroFuncs = new CoroHashMap();
@@ -49,6 +53,9 @@ static void changeCoroStats(const char *func, int change) {
 	(*s_coroFuncs)[func] += change;
 }
 
+/**
+ * Display the details of active coroutines
+ */
 static void displayCoroStats() {
 	debug("%d active coros", s_coroCount);
 
@@ -65,6 +72,9 @@ static void displayCoroStats() {
 }
 #endif
 
+/**
+ * Creates a coroutine context
+ */
 CoroBaseContext::CoroBaseContext(const char *func)
 	: _line(0), _sleep(0), _subctx(0) {
 #ifdef COROUTINE_DEBUG
@@ -74,6 +84,9 @@ CoroBaseContext::CoroBaseContext(const char *func)
 #endif
 }
 
+/**
+ * Destructor for coroutine context
+ */
 CoroBaseContext::~CoroBaseContext() {
 #ifdef COROUTINE_DEBUG
 	s_coroCount--;
@@ -499,7 +512,7 @@ void CoroutineScheduler::waitForMultipleObjects(CORO_PARAM, int nCount, uint32 *
 
 /**
  * Make the active process sleep for the given duration in milliseconds
- * @param duration					Duration in milliseconds
+ * @param duration		Duration in milliseconds
  * @remarks		This duration won't be precise, since it relies on the frequency the
  * scheduler is called.
  */
@@ -530,9 +543,9 @@ void CoroutineScheduler::sleep(CORO_PARAM, uint32 duration) {
  * Creates a new process.
  *
  * @param pid	process identifier
- * @param CORO_ADDR	coroutine start address
- * @param pParam	process specific info
- * @param sizeParam	size of process specific info
+ * @param CORO_ADDR		Coroutine start address
+ * @param pParam		Process specific info
+ * @param sizeParam		Size of process specific info
  */
 PROCESS *CoroutineScheduler::createProcess(uint32 pid, CORO_ADDR coroAddr, const void *pParam, int sizeParam) {
 	PROCESS *pProc;
@@ -601,9 +614,9 @@ PROCESS *CoroutineScheduler::createProcess(uint32 pid, CORO_ADDR coroAddr, const
 /**
  * Creates a new process with an auto-incrementing Process Id.
  *
- * @param CORO_ADDR	coroutine start address
- * @param pParam	process specific info
- * @param sizeParam	size of process specific info
+ * @param CORO_ADDR		Coroutine start address
+ * @param pParam		Process specific info
+ * @param sizeParam		Size of process specific info
  */
 uint32 CoroutineScheduler::createProcess(CORO_ADDR coroAddr, const void *pParam, int sizeParam) {
 	PROCESS *pProc = createProcess(++pidCounter, coroAddr, pParam, sizeParam);
@@ -613,9 +626,9 @@ uint32 CoroutineScheduler::createProcess(CORO_ADDR coroAddr, const void *pParam,
 /**
  * Creates a new process with an auto-incrementing Process Id, and a single pointer parameter.
  *
- * @param CORO_ADDR	coroutine start address
- * @param pParam	process specific info
- * @param sizeParam	size of process specific info
+ * @param CORO_ADDR		Coroutine start address
+ * @param pParam		Process specific info
+ * @param sizeParam		Size of process specific info
  */
 uint32 CoroutineScheduler::createProcess(CORO_ADDR coroAddr, const void *pParam) {
 	return createProcess(coroAddr, &pParam, sizeof(void *));
@@ -625,7 +638,7 @@ uint32 CoroutineScheduler::createProcess(CORO_ADDR coroAddr, const void *pParam)
 /**
  * Kills the specified process.
  *
- * @param pKillProc	which process to kill
+ * @param pKillProc		Which process to kill
  */
 void CoroutineScheduler::killProcess(PROCESS *pKillProc) {
 	// make sure a valid process pointer
@@ -674,7 +687,7 @@ PROCESS *CoroutineScheduler::getCurrentProcess() {
 /**
  * Returns the process identifier of the specified process.
  *
- * @param pProc	which process
+ * @param pProc			Which process
  */
 int CoroutineScheduler::getCurrentPID() const {
 	PROCESS *pProc = pCurrent;
@@ -690,9 +703,9 @@ int CoroutineScheduler::getCurrentPID() const {
  * Kills any process matching the specified PID. The current
  * process cannot be killed.
  *
- * @param pidKill	process identifier of process to kill
- * @param pidMask	mask to apply to process identifiers before comparison
- * @return The number of processes killed is returned.
+ * @param pidKill		Process identifier of process to kill
+ * @param pidMask		Mask to apply to process identifiers before comparison
+ * @return		The number of processes killed is returned.
  */
 int CoroutineScheduler::killMatchingProcess(uint32 pidKill, int pidMask) {
 	int numKilled = 0;
@@ -750,7 +763,7 @@ int CoroutineScheduler::killMatchingProcess(uint32 pidKill, int pidMask) {
  * called by killProcess() to allow the resource allocator to free
  * resources allocated to the dying process.
  *
- * @param pFunc	Function to be called by killProcess()
+ * @param pFunc			Function to be called by killProcess()
  */
 void CoroutineScheduler::setResourceCallback(VFPTRPP pFunc) {
 	pRCfunction = pFunc;
@@ -778,9 +791,9 @@ EVENT *CoroutineScheduler::getEvent(uint32 pid) {
 
 /**
  * Creates a new event object
- * @param bManualReset					Events needs to be manually reset. Otherwise, events
+ * @param bManualReset		Events needs to be manually reset. Otherwise, events
  * will be automatically reset after a process waits on the event finishes
- * @param bInitialState					Specifies whether the event is signalled or not initially
+ * @param bInitialState		Specifies whether the event is signalled or not initially
  */
 uint32 CoroutineScheduler::createEvent(bool bManualReset, bool bInitialState) {
 	EVENT *evt = new EVENT();
@@ -794,7 +807,7 @@ uint32 CoroutineScheduler::createEvent(bool bManualReset, bool bInitialState) {
 
 /**
  * Destroys the given event
- * @param pidEvent						Event PID
+ * @param pidEvent		Event Process Id
  */
 void CoroutineScheduler::closeEvent(uint32 pidEvent) {
 	EVENT *evt = getEvent(pidEvent);
@@ -806,7 +819,7 @@ void CoroutineScheduler::closeEvent(uint32 pidEvent) {
 
 /**
  * Sets the event
- * @param pidEvent						Event PID
+ * @param pidEvent		Event Process Id
  */
 void CoroutineScheduler::setEvent(uint32 pidEvent) {
 	EVENT *evt = getEvent(pidEvent);
@@ -816,7 +829,7 @@ void CoroutineScheduler::setEvent(uint32 pidEvent) {
 
 /**
  * Resets the event
- * @param pidEvent						Event PID
+ * @param pidEvent		Event Process Id
  */
 void CoroutineScheduler::resetEvent(uint32 pidEvent) {
 	EVENT *evt = getEvent(pidEvent);
@@ -827,7 +840,7 @@ void CoroutineScheduler::resetEvent(uint32 pidEvent) {
 /**
  * Temporarily sets a given event to true, and then runs all waiting processes, allowing any
  * processes waiting on the event to be fired. It then immediately resets the event again.
- * @param pidEvent						Event PID
+ * @param pidEvent		Event Process Id
  *
  * @remarks		Should not be run inside of another process
  */
@@ -880,5 +893,4 @@ void CoroutineScheduler::pulseEvent(uint32 pidEvent) {
 	evt->signalled = false;
 }
 
-
 } // end of namespace Common
diff --git a/common/coroutines.h b/common/coroutines.h
index 6df843887c..06af245ba7 100644
--- a/common/coroutines.h
+++ b/common/coroutines.h
@@ -65,7 +65,8 @@ typedef CoroBaseContext *CoroContext;
 
 /** This is a special constant that can be temporarily used as a parameter to call coroutine-ised
  * from methods from methods that haven't yet been converted to being a coroutine, so code at least
- * compiles correctly. Be aware, though, that if you use this, you will get runtime errors.
+ * compiles correctly. Be aware, though, that an error will occur if a coroutine that was passed
+ * the nullContext tries to sleep or yield control.
  */
 extern CoroContext nullContext;
 
@@ -283,6 +284,7 @@ public:
 #define CORO_INFINITE 0xffffffff
 #define CORO_INVALID_PID_VALUE 0
 
+/** Coroutine parameter for methods converted to coroutines */
 typedef void (*CORO_ADDR)(CoroContext &, const void *);
 
 /** process structure */