TONY: Converting method comments to DOXYGEN format

2 files changed, 503 insertions, 972 deletions

diff --git a/engines/tony/mpal/mpal.cpp b/engines/tony/mpal/mpal.cpp
index f049ecf3ea..a173b707f2 100644
--- a/engines/tony/mpal/mpal.cpp
+++ b/engines/tony/mpal/mpal.cpp
@@ -61,6 +61,8 @@ namespace Tony {
 
 namespace MPAL {
 
+#define GETARG(type)   va_arg(v, type)
+
 /****************************************************************************\
 *       Copyright
 \****************************************************************************/
@@ -76,39 +78,25 @@ const char *mpalCopyright =
 *       Internal functions
 \****************************************************************************/
 
-/****************************************************************************\
-*
-* Function:     void LockVar(void);
-*
-* Description:  Locka le variabili per accederci
-*
-\****************************************************************************/
-
+/**
+ * Locks the variables for access
+ */
 void LockVar(void) {
 	GLOBALS.lpmvVars = (LPMPALVAR)GlobalLock(GLOBALS.hVars);
 }
 
-/****************************************************************************\
-*
-* Function:     void UnlockVar(void);
-*
-* Description:  Unlocka le variabili dopo l'uso
-*
-\****************************************************************************/
 
+/**
+ * Unlocks variables after use
+ */
 void UnlockVar(void) {
 	GlobalUnlock(GLOBALS.hVars);
 }
 
 
-/****************************************************************************\
-*
-* Function:     void LockMsg(void);
-*
-* Description:  Locka i messaggi per accederci
-*
-\****************************************************************************/
-
+/**
+ * Locks the messages for access
+ */
 static void LockMsg(void) {
 #ifdef NEED_LOCK_MSGS
 	GLOBALS.lpmmMsgs = (LPMPALMSG)GlobalLock(GLOBALS.hMsgs);
@@ -116,14 +104,9 @@ static void LockMsg(void) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     void UnlockMsg(void);
-*
-* Description:  Unlocka i messaggi dopo l'uso
-*
-\****************************************************************************/
-
+/**
+ * Unlocks the messages after use
+ */
 static void UnlockMsg(void) {
 #ifdef NEED_LOCK_MSGS
 	GlobalUnlock(GLOBALS.hMsgs);
@@ -131,125 +114,79 @@ static void UnlockMsg(void) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     void LockDialogs(void);
-*
-* Description:  Locka i dialoghi per accederci
-*
-\****************************************************************************/
-
+/**
+ * Locks the dialogs for access
+ */
 static void LockDialogs(void) {
 	GLOBALS.lpmdDialogs = (LPMPALDIALOG)GlobalLock(GLOBALS.hDialogs);
 }
 
 
-/****************************************************************************\
-*
-* Function:     void UnlockDialogs(void);
-*
-* Description:  Unlocka i dialoghi dopo l'uso
-*
-\****************************************************************************/
-
+/**
+ * Unlocks the dialogs after use
+ */
 static void UnlockDialogs(void) {
 	GlobalUnlock(GLOBALS.hDialogs);
 }
 
 
-/****************************************************************************\
-*
-* Function:     void LockLocations(void);
-*
-* Description:  Locka le strutture di dati sulle locazioni
-*
-\****************************************************************************/
-
+/**
+ * Locks the location data structures for access
+ */
 static void LockLocations(void) {
 	GLOBALS.lpmlLocations = (LPMPALLOCATION)GlobalLock(GLOBALS.hLocations);
 }
 
 
-/****************************************************************************\
-*
-* Function:     void UnlockLocations(void);
-*
-* Description:  Unlocka le strutture di dati sulle locazioni
-*
-\****************************************************************************/
-
+/**
+ * Unlocks the location structures after use
+ */
 static void UnlockLocations(void) {
 	GlobalUnlock(GLOBALS.hLocations);
 }
 
 
-/****************************************************************************\
-*
-* Function:     void LockItems(void);
-*
-* Description:  Locka le strutture di dati sugli item
-*
-\****************************************************************************/
-
+/**
+ * Locks the items structures for use
+ */
 static void LockItems(void) {
 	GLOBALS.lpmiItems = (LPMPALITEM)GlobalLock(GLOBALS.hItems);
 }
 
 
-/****************************************************************************\
-*
-* Function:     void UnlockItems(void);
-*
-* Description:  Unlocka le strutture di dati sugli item
-*
-\****************************************************************************/
-
+/**
+ * Unlocks the items structures after use
+ */
 static void UnlockItems(void) {
 	GlobalUnlock(GLOBALS.hItems);
 }
 
-/****************************************************************************\
-*
-* Function:     void LockScripts(void);
-*
-* Description:  Locka le strutture di dati sugli script
-*
-\****************************************************************************/
 
+/**
+ * Locks the script data structures for use
+ */
 static void LockScripts(void) {
 	GLOBALS.lpmsScripts = (LPMPALSCRIPT)GlobalLock(GLOBALS.hScripts);
 }
 
 
-/****************************************************************************\
-*
-* Function:     void UnlockScripts(void);
-*
-* Description:  Unlocka le strutture di dati sugli script
-*
-\****************************************************************************/
-
+/**
+ * Unlocks the script data structures after use
+ */
 static void UnlockScripts(void) {
 	GlobalUnlock(GLOBALS.hScripts);
 }
 
 
-/****************************************************************************\
-*
-* Function:     int varGetValue(char * lpszVarName);
-*
-* Description:  Restituisce il valore corrente di una variabile globale
-*
-* Input:        char * lpszVarName       Nome della variabile
-*
-* Return:       Valore corrente
-*
-* Note:         Prima di questa funzione, bisogna richiamare LockVar() che
-*               locka le variabili globali per l'utilizzo. Dopo inoltre bi-
-*               sogna ricordarsi di chiamare UnlockVar()
-*
-\****************************************************************************/
-
+/**
+ * Returns the current value of a global variable
+ *
+ * @param lpszVarName		Name of the variable
+ * @returns		Current value
+ * @remarks		Before using this method, you must call LockVar() to
+ * lock the global variablves for use. Then afterwards, you will
+ * need to remember to call UnlockVar()
+ */
 int32 varGetValue(const char *lpszVarName) {
 	int i;
 	LPMPALVAR v=GLOBALS.lpmvVars;
@@ -263,17 +200,11 @@ int32 varGetValue(const char *lpszVarName) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     void varSetValue(char * lpszVarName, int val);
-*
-* Description:  Setta un nuovo valore per una variabile globale di MPAL
-*
-* Input:        char * lpszVarName       Nome della variabile
-*               int val                 Valore da settare
-*
-\****************************************************************************/
-
+/**
+ * Sets the value of a MPAL global variable
+ * @param lpszVarName       Name of the variable
+ * @param val				Value to set
+ */
 void varSetValue(const char *lpszVarName, int32 val) {
 	uint i;
 	LPMPALVAR v = GLOBALS.lpmvVars;
@@ -298,22 +229,14 @@ void varSetValue(const char *lpszVarName, int32 val) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     int locGetOrderFromNum(uint32 nLoc);
-*
-* Description:  Trova l'indice della locazione #nLoc all'interno dell'array
-*               delle strutture delle locazioni
-*
-* Input:        uint32 nLoc              Numero della locazione da cercare
-*
-* Return:       Indice, o -1 se la locazione non e' presente
-*
-* Note:         Per funzionare, la funzione necessita che le locazioni siano
-*               state lockate con LockLoc()
-*
-\****************************************************************************/
-
+/**
+ * Find the index of a location within the location array. Remember to call LockLoc() beforehand.
+ *
+ * @param nLoc				Location number to search for
+ * @returns		Index, or -1 if the location is not present
+ * @remarks		This function requires the location list to have
+ * first been locked with a call to LockLoc().
+ */
 static int locGetOrderFromNum(uint32 nLoc) {
 	int i;
 	LPMPALLOCATION loc = GLOBALS.lpmlLocations;
@@ -325,22 +248,14 @@ static int locGetOrderFromNum(uint32 nLoc) {
 	return -1;
 }
 
-/****************************************************************************\
-*
-* Function:     int msgGetOrderFromNum(uint32 nMsg);
-*
-* Description:  Trova l'indice del messaggio #nMsg all'interno dell'array
-*               delle strutture dei messaggi
-*
-* Input:        uint32 nMsg              Numero del messaggio da cercare
-*
-* Return:       Indice, o -1 se il messaggio non e' presente
-*
-* Note:         Per funzionare, la funzione necessita che i messaggi siano
-*               stati lockati con LockMsg()
-*
-\****************************************************************************/
 
+/**
+ * Find the index of a message within the messages array
+ * @param nMsg				Message number to search for
+ * @returns		Index, or -1 if the message is not present
+ * @remarks		This function requires the message list to have
+ * first been locked with a call to LockMsg()
+ */
 static int msgGetOrderFromNum(uint32 nMsg) {
 	int i;
 	LPMPALMSG msg = GLOBALS.lpmmMsgs;
@@ -352,23 +267,13 @@ static int msgGetOrderFromNum(uint32 nMsg) {
 	return -1;
 }
 
-
-/****************************************************************************\
-*
-* Function:     int itemGetOrderFromNum(uint32 nItem);
-*
-* Description:  Trova l'indice dell'item #nItem all'interno dell'array delle
-*               strutture degli item
-*
-* Input:        uint32 nItem             Numero dell'item da cercare
-*
-* Return:       Indice, o -1 se l'item non e' presente
-*
-* Note:         Per funzionare, questa funzione necessita che gli item siano
-*               stati lockati tramite LockItem()
-*
-\****************************************************************************/
-
+/**
+ * Find the index of an item within the items array
+ * @param nItem				Item number to search for
+ * @returns		Index, or -1 if the item is not present
+ * @remarks		This function requires the item list to have
+ * first been locked with a call to LockItems()
+ */
 static int itemGetOrderFromNum(uint32 nItem) {
 	int i;
 	LPMPALITEM item = GLOBALS.lpmiItems;
@@ -381,22 +286,13 @@ static int itemGetOrderFromNum(uint32 nItem) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     int scriptGetOrderFromNum(uint32 nScript);
-*
-* Description:  Trova l'indice dello script #nScript all'interno dell'array
-*               delle strutture degli script
-*
-* Input:        uint32 nScript           Numero dello script da cercare
-*
-* Return:       Indice, o -1 se lo script non e' presente
-*
-* Note:         Per funzionare, questa funzione necessita che gli script siano
-*               stati lockati tramite LockScript()
-*
-\****************************************************************************/
-
+/**
+ * Find the index of a script within the scripts array
+ * @param nScript			Script number to search for
+ * @returns		Index, or -1 if the script is not present
+ * @remarks		This function requires the script list to have
+ * first been locked with a call to LockScripts()
+ */
 static int scriptGetOrderFromNum(uint32 nScript) {
 	int i;
 	LPMPALSCRIPT script = GLOBALS.lpmsScripts;
@@ -409,22 +305,13 @@ static int scriptGetOrderFromNum(uint32 nScript) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     int dialogGetOrderFromNum(uint32 nDialog);
-*
-* Description:  Trova l'indice del dialog #nDialog all'interno dell'array
-*               delle strutture dei dialog
-*
-* Input:        uint32 nDialog           Numero del dialog da cercare
-*
-* Return:       Indice, o -1 se il dialog non e' presente
-*
-* Note:         Per funzionare, questa funzione necessita che i dialog siano
-*               stati lockati tramite LockDialogs()
-*
-\****************************************************************************/
-
+/**
+ * Find the index of a dialog within the dialogs array
+ * @param nDialog			Dialog number to search for
+ * @returns		Index, or -1 if the dialog is not present
+ * @remarks		This function requires the dialog list to have
+ * first been locked with a call to LockDialogs()
+ */
 static int dialogGetOrderFromNum(uint32 nDialog) {
 	int i;
 	LPMPALDIALOG dialog = GLOBALS.lpmdDialogs;
@@ -437,21 +324,12 @@ static int dialogGetOrderFromNum(uint32 nDialog) {
 }
 
 
-
-/****************************************************************************\
-*
-* Function:     char * DuplicateMessage(uint32 nMsgOrd);
-*
-* Description:  Duplica un messaggio
-*
-* Input:        uint32 nMsgOrd           Indice del messaggio dentro l'array
-*                                       di strutture dei messaggi
-*
-* Return:       Pointer al messaggio duplicato (che puo' essere liberato
-*               con GlobalFree()).
-*
-\****************************************************************************/
-
+/**
+ * Duplicates a message
+ * @param nMsgOrd			Index of the message inside the messages array
+ * @returns		Pointer to the duplicated message.
+ * @remarks		Remember to free the duplicated message when done with it.
+ */
 static char *DuplicateMessage(uint32 nMsgOrd) {
 	const char *origmsg;
 	char *clonemsg;
@@ -478,22 +356,13 @@ static char *DuplicateMessage(uint32 nMsgOrd) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     char * DuplicateDialogPeriod(uint32 nDlgOrd, uint32 nPeriod);
-*
-* Description:  Duplica una frase di un dialog
-*
-* Input:        uint32 nDlgOrd           Indice del dialogo dentro l'array di
-*                                       strutture dei dialoghi
-*
-*               uint32 nPeriod           Numero della frase da duplicare
-*
-* Return:       Pointer alla frase duplicata (che puo' essere liberata con
-*               GlobalFree()).
-*
-\****************************************************************************/
-
+/**
+ * Duplicate a sentence of a dialog
+ * @param nDlgOrd			Index of the dialog in the dialogs array
+ * @param nPeriod           Sentence number to be duplicated.
+ * @returns		Pointer to the duplicated phrase. Remember to free it
+ * when done with it.
+ */
 static char *DuplicateDialogPeriod(uint32 nPeriod) {
 	const char *origmsg;
 	char *clonemsg;
@@ -524,19 +393,12 @@ static char *DuplicateDialogPeriod(uint32 nPeriod) {
 }
 
 
-
-/****************************************************************************\
-*
-* Function:     HGLOBAL resLoad(uint32 dwId);
-*
-* Description:  Carica una risorsa dal file MPR
-*
-* Input:        uint32 dwId              ID della risorsa da caricare
-*
-* Return:       Handle alla memoria in cui si trova la risorsa
-*
-\****************************************************************************/
-
+/**
+ * Load a resource from the MPR file
+ *
+ * @param dwId				ID of the resource to load
+ * @returns		Handle to the loaded resource
+ */
 HGLOBAL resLoad(uint32 dwId) {
 	int i;
 	HGLOBAL h;
@@ -736,21 +598,13 @@ static LPITEM GetItemData(uint32 nOrdItem) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     void CustomThread(LPCFCALL p);
-*
-* Description:  Thread che richiama una funzione custom. Viene usato negli
-*               script, in modo che ciascuna funzione venga eseguita senza
-*               ritardare le altre
-*
-* Input:        LPCFCALL p              Struttura che definisce la chiamata
-*
-* Note:         La struttura passata come parametro viene freeata con
-*               GlobalFree() alla fine dell'esecuzione.
-*
-\****************************************************************************/
-
+/** 
+ * Thread that calls a custom function. It is used in scripts, so that each script
+ * function is executed without delaying the others.
+ *
+ * @param param				pointer to a pointer to the structure that defines the call.
+ * @remarks		The passed structure is freed when the process finishes.
+ */
 void CustomThread(CORO_PARAM, const void *param) {
 	CORO_BEGIN_CONTEXT;
 		LPCFCALL p;
@@ -768,20 +622,12 @@ void CustomThread(CORO_PARAM, const void *param) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     void ScriptThread(LPMPALSCRIPT s);
-*
-* Description:  Esegue uno script. Questa funzione e' pensata come starting
-*               point per un thread
-*
-* Input:        LPMPALSCRIPT s          Script da eseguire
-*
-* Note:         Lo script passato come parametro viene, alla fine dell'ese-
-*               cuzione, freeato con una GlobalFree()
-*
-\****************************************************************************/
-
+/**
+ * Main process for running a script.
+ *
+ * @param param				Pointer to a pointer to a structure containing the script data.
+ * @remarks		The passed structure is freed when the process finishes.
+ */
 void ScriptThread(CORO_PARAM, const void *param) {
 	CORO_BEGIN_CONTEXT;
 		uint i, j, k;
@@ -866,20 +712,13 @@ void ScriptThread(CORO_PARAM, const void *param) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     void ActionThread(LPMPALITEM item);
-*
-* Description:  Thread che esegue una azione su un item. Il thread
-*               esegue sempre l'azione 0, per cui e' necessario creare
-*               un item nuovo in cui l'azione 0 sia quella richiesta.
-*               Inoltre non viene controllata l'espressione when, ma viene
-*               sempre eseguita l'azione.
-*
-* Input:        LPMPALITEM item         Item che contiene l'azione
-*
-\****************************************************************************/
-
+/**
+ * Thread that performs an action on an item. the thread always executes the action, 
+ * so it should create a new item in which the action is the one required.
+ * Furthermore, the expression is not checked, but it is always performed the action.
+ *
+ * @param param				Pointer to a pointer to a structure containing the action.
+ */
 void ActionThread(CORO_PARAM, const void *param) {
 	// COROUTINE
 	CORO_BEGIN_CONTEXT;
@@ -935,8 +774,8 @@ void ActionThread(CORO_PARAM, const void *param) {
 
 /**
  * This thread monitors a created action to detect when it ends.
- * @remarks				Since actions can spawn sub-actions, this needs to be a
- *						separate thread to determine when the outer action is done
+ * @remarks		Since actions can spawn sub-actions, this needs to be a
+ * separate thread to determine when the outer action is done
  */
 void ShutUpActionThread(CORO_PARAM, const void *param) {
 	// COROUTINE
@@ -956,18 +795,12 @@ void ShutUpActionThread(CORO_PARAM, const void *param) {
 	CORO_END_CODE;
 }
 
-/****************************************************************************\
-*
-* Function:     void LocationPollThread(uint32 id);
-*
-* Description:  Esegue il polling di una locazione (starting point di un
-*               thread).
-*
-* Input:        uint32 id                Indice per gli array relativi ai
-*                                       polling degli item delle locazioni
-*
-\****************************************************************************/
 
+/**
+ * Polls one location (starting point of a process)
+ *
+ * @param param				Pointer to an index in the array of polling locations.
+ */
 void LocationPollThread(CORO_PARAM, const void *param) {
 	typedef struct {
 		uint32 nItem, nAction;
@@ -1257,22 +1090,17 @@ void LocationPollThread(CORO_PARAM, const void *param) {
 
 
 
-/****************************************************************************\
-*
-* Function:     void ShutUpDialogThread(HANDLE hThread);
-*
-* Description:  Aspetta la fine dell'esecuzione del dialog thread e ripri-
-*               stina le variabili globali indicando che il dialogo e' finito.
-*
-* Input:        HANDLE hThread          Handle del dialog thread
-*
-* Note:         Si ricorre a questo thread aggiuntivo, al posto di azzerare
-*               le variabili all'interno del dialog thread stesso, poiche',
-*               a causa della natura ricorsiva di un dialogo, non e' sempre
-*               possibile sapere quando esattamente finisce un dialogo.
-*
-\****************************************************************************/
 
+
+/**
+ * Wait for the end of the dialog execution thread, and then restore global 
+ * variables indicating that the dialogue has finished.
+ *
+ * @param param				Pointer to a handle to the dialog 
+ * @remarks		This additional process is used, instead of clearing variables
+ * within the same dialog thread, because due to the recursive nature of a dialog,
+ * it would be difficult to know within it when the dialog is actually ending.
+ */
 void ShutUpDialogThread(CORO_PARAM, const void *param) {
 	CORO_BEGIN_CONTEXT;
 	CORO_END_CONTEXT(_ctx);
@@ -1296,9 +1124,10 @@ void ShutUpDialogThread(CORO_PARAM, const void *param) {
 
 void DoChoice(CORO_PARAM, uint32 nChoice);
 
+
 /**
  * Executes a group of the current dialog. Can 'be the Starting point of a process.
- * @parm nGroup					Number of the group to perform
+ * @parm nGroup				Number of the group to perform
  */
 void GroupThread(CORO_PARAM, const void *param) {
 	CORO_BEGIN_CONTEXT;
@@ -1371,16 +1200,11 @@ void GroupThread(CORO_PARAM, const void *param) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     void DoChoice(uint32 nChoice);
-*
-* Description:  Esegue una scelta nel dialogo corrente
-*
-* Input:        uint32 nChoice           Numero della scelta da eseguire
-*
-\****************************************************************************/
-
+/**
+ * Make a choice in the current dialog.
+ *
+ * @param nChoice			Number of choice to perform
+ */
 void DoChoice(CORO_PARAM, uint32 nChoice) {
 	CORO_BEGIN_CONTEXT;
 		LPMPALDIALOG dialog;
@@ -1476,29 +1300,18 @@ void DoChoice(CORO_PARAM, uint32 nChoice) {
 }
 
 
-
-/****************************************************************************\
-*
-* Function:     HANDLE DoAction(uint32 nAction, uint32 ordItem, uint32 dwParam);
-*
-* Description:  Esegue una azione su un certo item
-*
-* Input:        uint32 nAction           Numero dell'azione
-*               uint32 ordItem           Indice dell'item nelle strutture
-*                                       degli item
-*               uint32 dwParam           Eventuale parametro per l'azione
-*
-* Return:       Handle del thread che sta eseguendo l'azione, oppure
-*               CORO_INVALID_PID_VALUE se l'azione non e' definita, o l'item
-*               e' disattivato.
-*
-* Note:         Si puo' ottenere l'indice dell'item a partire dal suo numero
-*               tramite la funzione itemGetOrderFromNum().
-*               Gli item devono essere lockati, perche' questa funzione
-*               funzioni, tramite LockItem();
-*
-\****************************************************************************/
-
+/**
+ * Perform an action on a certain item.
+ *
+ * @param nAction			Action number
+ * @param ordItem           Index of the item in the items list
+ * @param dwParam			Any parameter for the action.
+ * @returns		Id of the process that was launched to perform the action, or
+ * CORO_INVALID_PID_VALUE if the action was not defined, or the item was inactive.
+ * @remarks		You can get the index of an item from it's number by using
+ * the itemGetOrderFromNum() function. The items list must first be locked
+ * by calling LockItem().
+ */
 static uint32 DoAction(uint32 nAction, uint32 ordItem, uint32 dwParam) {
 	LPMPALITEM item = GLOBALS.lpmiItems;
 	int i;
@@ -1594,20 +1407,14 @@ static uint32 DoDialog(uint32 nDlgOrd, uint32 nGroup) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     bool DoSelection(uint32 nChoice, uint32 dwData);
-*
-* Description:  Prende nota del select scelto dall'utente, e avverte il
-*               thread che stava eseguendo il dialogo che puo' continuare.
-*
-* Input:        uint32 nChoice           Numero della scelta che era in corso
-*               uint32 dwData            Dato abbinato al select selezionato
-*
-* Return:       true se tutto OK, false in caso di errore
-*
-\****************************************************************************/
-
+/**
+ * Takes note of the selection chosen by the user, and warns the process that was running 
+ * the box that it can continue.
+ *
+ * @param nChoice           Number of choice that was in progress
+ * @param dwData			Since combined with select selection
+ * @returns		True if everything is OK, false on failure
+ */
 bool DoSelection(uint32 i, uint32 dwData) {
 	LPMPALDIALOG dialog=GLOBALS.lpmdDialogs+GLOBALS.nExecutingDialog;
 	int j;
@@ -1625,30 +1432,18 @@ bool DoSelection(uint32 i, uint32 dwData) {
 }
 
 
+/**
+ * @defgroup Exported functions
+ */
 
-/****************************************************************************\
-*       Exported functions
-\****************************************************************************/
-
-/****************************************************************************\
-*
-* Function:     bool mpalInit(LPSTR lpszMpcFileName, LPSTR lpszMprFileName,
-*                 LPLPCUSTOMFUNCTION lplpcfArray);
-*
-* Description:  Inizializza la libreria MPAL, e apre un file .MPC, che
-*               verra' utilizzato per tutte le query
-*
-* Input:        char * lpszMpcFileName   Nome del file .MPC, comprensivo di
-*                                       estensione
-*               char * lpszMprFileName   Nome del file .MPR, comprensivo di
-*                                       estensione
-*               LPLPCUSTOMFUNCTION
-*                 lplpcfArray           Array di pointer a funzioni custom
-*
-* Return:       true se tutto OK, false in caso di errore
-*
-\****************************************************************************/
-
+/**
+ * Initialises the MPAL library and opens the .MPC file, which will be used for all queries.
+ *
+ * @param lpszMpcFileName   Name of the MPC file
+ * @param lpszMprFileName   Name of the MPR file
+ * @param lplpcfArray		Array of pointers to custom functions.
+ * @returns		True if everything is OK, false on failure
+ */
 bool mpalInit(const char *lpszMpcFileName, const char *lpszMprFileName, 
 			  LPLPCUSTOMFUNCTION lplpcfArray, Common::String *lpcfStrings) {
 	Common::File hMpc;
@@ -1803,34 +1598,15 @@ bool mpalInit(const char *lpszMpcFileName, const char *lpszMprFileName,
 	return true;
 }
 
-/****************************************************************************\
-*
-* Function:     uint32 mpalQuery(uint16 wQueryType, ...);
-*
-* Description:  Questa e' la funzione generale per comunicare con la libreria,
-*               per richiedere informazioni riguardo a quanto si trova nel
-*               file .MPC
-*
-* Input:        uint16 wQueryType         Tipo di query. La lista e' in
-*                                       enum QueryTypes
-*
-* Return:       4 bytes che dipendono dal tipo di query
-*
-* Note:         E' _FORTEMENTE_ consigliato utilizzare le macro
-*               definite sopra per utilizzare le query, dato che
-*               permettono di evitare spiacevoli bug dovuti a dimenticanze
-*               di parametri.
-*
-\****************************************************************************/
-
-#define GETARG(type)   va_arg(v, type)
 
 /**
- * MPAL Query variation #1 - dword return
- * This variation handles mpal query types that need to return a dword result.
+ * This is a general function to communicate with the library, to request information
+ * about what is in the .MPC file
  *
- * @param wQueryType					Query type
- * @param v								Variable length argument list
+ * @param wQueryType		Type of query. The list is in the QueryTypes enum.
+ * @returns		4 bytes depending on the type of query
+ * @remarks		This is the specialised version of the original single mpalQuery
+ * method that returns numeric results.
  */
 uint32 mpalQueryDWORD(uint16 wQueryType, ...) {
 	int x, y, z;
@@ -1844,6 +1620,7 @@ uint32 mpalQueryDWORD(uint16 wQueryType, ...) {
 	GLOBALS.mpalError = OK;
 
 	if (wQueryType == MPQ_VERSION) {
+
 		/*
 		 *  uint32 mpalQuery(MPQ_VERSION);
 		 */
@@ -2021,11 +1798,13 @@ uint32 mpalQueryDWORD(uint16 wQueryType, ...) {
 }
 
 /**
- * MPAL Query variation #1 - dword return
- * This variation handles mpal query types that need to return a pointer/handle result
+ * This is a general function to communicate with the library, to request information
+ * about what is in the .MPC file
  *
- * @param wQueryType					Query type
- * @param v								Variable length argument list
+ * @param wQueryType		Type of query. The list is in the QueryTypes enum.
+ * @returns		4 bytes depending on the type of query
+ * @remarks		This is the specialised version of the original single mpalQuery
+ * method that returns a pointer or handle.
  */
 HANDLE mpalQueryHANDLE(uint16 wQueryType, ...) {
 	int x, y;
@@ -2176,13 +1955,15 @@ HANDLE mpalQueryHANDLE(uint16 wQueryType, ...) {
 	return hRet;
 }
 
+
 /**
- * MPAL Query variation #1 - dword return
- * This variation handles mpal query types that need to return a pointer/handle result
+ * This is a general function to communicate with the library, to request information
+ * about what is in the .MPC file
  *
- * @param wQueryType					Query type
- * @param dwRet							DWORD return value (when coroutine method completes)
- * @param v								Variable length argument list
+ * @param wQueryType		Type of query. The list is in the QueryTypes enum.
+ * @returns		4 bytes depending on the type of query
+ * @remarks		This is the specialised version of the original single mpalQuery
+ * method that needs to run within a co-routine context.
  */
 void mpalQueryCORO(CORO_PARAM, uint16 wQueryType, uint32 *dwRet, ...) {
 	CORO_BEGIN_CONTEXT;
@@ -2216,34 +1997,22 @@ void mpalQueryCORO(CORO_PARAM, uint16 wQueryType, uint32 *dwRet, ...) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     uint32 mpalGetError(void);
-*
-* Description:  Ritorna il codice di errore corrente di MPAL
-*
-* Return:       Codice di errore
-*
-\****************************************************************************/
-
+/**
+ * Returns the current MPAL error code
+ *
+ * @returns		Error code
+ */
 uint32 mpalGetError(void) {
 	return GLOBALS.mpalError;
 }
 
 
-/****************************************************************************\
-*
-* Function:     void mpalExecuteScript(int nScript);
-*
-* Description:  Esegue uno script. Lo script viene eseguito in multitasking
-*               tramite un thread.
-*
-* Input:        int nScript             Numero dello script da eseguire
-*
-* Return:       true se lo script e' stato avviato, false in caso di errore
-*
-\****************************************************************************/
-
+/**
+ * Execute a script. The script runs on multitasking by a thread.
+ *
+ * @param nScript			Script number to run
+ * @returns		TRUE if the script 'was launched, FALSE on failure
+ */
 bool mpalExecuteScript(int nScript) {
 	int n;
 	LPMPALSCRIPT s;
@@ -2265,38 +2034,26 @@ bool mpalExecuteScript(int nScript) {
 }
 
 
-/****************************************************************************\
-*
-* Function:     void mpalInstallItemIrq(LPITEMIRQFUNCTION GLOBALS.lpiifCustom);
-*
-* Description:  Install a custom routine that will be called by MPAL every
-*               time the pattern of an item has been changed.
-*
-* Input:        LPITEMIRQFUNCTION GLOBALS.lpiifCustom   Custom function to install
-*
-\****************************************************************************/
-
+/**
+ * Install a custom routine That will be called by MPAL every time the pattern 
+ * of an item has been changed.
+ *
+ * @param lpiifCustom		Custom function to install
+ */
 void mpalInstallItemIrq(LPITEMIRQFUNCTION lpiifCus) {
 	GLOBALS.lpiifCustom = lpiifCus;
 }
 
 
-/****************************************************************************\
-*
-* Function:     bool mpalStartIdlePoll(int nLoc);
-*
-* Description:  Process the idle actions of the items on one location.
-*
-* Input:        int nLoc                Number of the location whose items
-*                                       must be processed for idle actions.
-*
-* Return:       true se tutto OK, false se si e' superato il limite massimo.
-*
-* Note:         Il numero massimo delle locazione che e' possibile pollare
-*               contemporaneamente e' contenuto nel define MAXPOLLINGFUNCIONS
-*
-\****************************************************************************/
-
+/**
+ * Process the idle actions of the items on one location.
+ *
+ * @param nLoc				Number of the location whose items must be processed 
+ * for idle actions.
+ * @returns		TRUE if all OK, and FALSE if it exceeded the maximum limit.
+ * @remarks		The maximum number of locations that can be polled
+ * simultaneously is defined defined by MAXPOLLINGFUNCIONS
+ */
 bool mpalStartIdlePoll(int nLoc) {
 	uint32 i;
 
@@ -2322,20 +2079,13 @@ bool mpalStartIdlePoll(int nLoc) {
 }
 
 
-
-/****************************************************************************\
-*
-* Function:     bool mpalEndIdlePoll(int nLoc);
-*
-* Description:  Stop processing the idle actions of the items on one location.
-*
-* Input:        int nLoc                Number of the location
-*
-* Return:       true se tutto OK, false se la locazione specificata non era
-*               in fase di polling
-*
-\****************************************************************************/
-
+/**
+ * Stop processing the idle actions of the items on one location.
+ *
+ * @param nLo				Number of the location
+ * @returns		TRUE if all OK, FALSE if the specified location was not
+ * in the process of polling
+ */
 void mpalEndIdlePoll(CORO_PARAM, int nLoc, bool *result) {
 	CORO_BEGIN_CONTEXT;
 		int i;
@@ -2365,33 +2115,22 @@ void mpalEndIdlePoll(CORO_PARAM, int nLoc, bool *result) {
 }
 
 
-
-/****************************************************************************\
-*
-* Function:     int mpalGetSaveStateSize(void);
-*
-* Description:  Acquire the length of a save state
-*
-* Return:       Length in bytes
-*
-\****************************************************************************/
-
+/**
+ * Retrieve the length of a save state
+ *
+ * @returns		Length in bytes
+ */
 int mpalGetSaveStateSize(void) {
 	return GLOBALS.nVars * sizeof(MPALVAR) + 4;
 }
 
 
-/****************************************************************************\
-*
-* Function:     void mpalSaveState(byte *buf);
-*
-* Description:  Store the save state into a buffer. The buffer must be
-*								length at least the size specified with mpalGetSaveStateSize
-*
-* Input:				byte *buf							Buffer where to store the state
-*
-\****************************************************************************/
-
+/**
+ * Store the save state into a buffer. The buffer must be
+ * length at least the size specified with mpalGetSaveStateSize
+ *
+ * @param buf				Buffer where to store the state
+ */
 void mpalSaveState(byte *buf) {
 	LockVar();
 	WRITE_LE_UINT32(buf, GLOBALS.nVars);
@@ -2399,18 +2138,13 @@ void mpalSaveState(byte *buf) {
 	UnlockVar();	
 }
 
-/****************************************************************************\
-*
-* Function:     int mpalLoadState(byte *buf);
-*
-* Description:  Load a save state from a buffer. 
-*
-* Input:				byte *buf							Buffer where to store the state
-*
-*	Return:				Length of the state in bytes
-*
-\****************************************************************************/
 
+/**
+ * Load a save state from a buffer.
+ *
+ * @param buf				Buffer where to store the state
+ * @returns		Length of the state buffer in bytes
+ */
 int mpalLoadState(byte *buf) {
 	// Dobbiamo distruggere tutte le variabili e ricrearle
 	GlobalFree(GLOBALS.hVars);
diff --git a/engines/tony/mpal/mpal.h b/engines/tony/mpal/mpal.h
index 319f71c6a8..a14bfd1895 100644
--- a/engines/tony/mpal/mpal.h
+++ b/engines/tony/mpal/mpal.h
@@ -127,6 +127,12 @@ namespace Tony {
 namespace MPAL {
 
 /****************************************************************************\
+*       Type definitions
+\****************************************************************************/
+
+typedef void *HANDLE;
+
+/****************************************************************************\
 *       Macro definitions and structures
 \****************************************************************************/
 
@@ -140,25 +146,19 @@ namespace MPAL {
 
 #define LPSTR char *
 
-/****************************************************************************\
-*       enum QueryCoordinates
-*       ---------------------
-* Description: Macro for use with queries that may refer to X and Y co-ordinates
-\****************************************************************************/
-
+/**
+ * Macro for use with queries that may refer to X and Y co-ordinates
+ */
 enum QueryCoordinates {
   MPQ_X,
   MPQ_Y
 };
 
 
-/****************************************************************************\
-*       enum QueryTypes
-*       ---------------
-* Description: Query can be used with mpalQuery methods. In practice corresponds
-*              all claims that can do at the library
-\****************************************************************************/
-
+/**
+ * Query can be used with mpalQuery methods. In practice corresponds all claims 
+ * that can do at the library
+ */
 enum QueryTypes {
   /* General Query */
   MPQ_VERSION=10,
@@ -189,13 +189,9 @@ enum QueryTypes {
   MPQ_DO_DIALOG
 };
 
-
-/****************************************************************************\
-*       typedef ITEM
-*       ------------
-* Description: Framework to manage the animation of an item
-\****************************************************************************/
-
+/**
+ * Framework to manage the animation of an item
+ */
 typedef struct {
   char *frames[MAXFRAMES];
   Common::Rect frameslocations[MAXFRAMES];
@@ -214,311 +210,188 @@ typedef struct {
 typedef ITEM *LPITEM;
 
 
-/****************************************************************************\
-*       typedef LPCUSTOMFUNCTION
-*       ------------------------
-* Description: Define a custom function, to use the language MPAL
-*              to perform various controls as a result of an action
-\****************************************************************************/
-
+/**
+ * Define a custom function, to use the language MPAL to perform various controls as a result of an action
+ */
 typedef void (*LPCUSTOMFUNCTION)(CORO_PARAM, uint32, uint32, uint32, uint32);
 typedef LPCUSTOMFUNCTION *LPLPCUSTOMFUNCTION;
 
-
-/****************************************************************************\
-*       typedef LPITEMIRQFUNCTION
-*       -------------------------
-* Description: Define an IRQ of an item that is called when the 
-*              pattern changes or the status of an item
-\****************************************************************************/
-
+/**
+ * 
+ * Define an IRQ of an item that is called when the  pattern changes or the status of an item
+ */
 typedef void (*LPITEMIRQFUNCTION)(uint32, int, int);
 typedef LPITEMIRQFUNCTION* LPLPITEMIRQFUNCTION;
 
+/**
+ * @defgroup Macrofunctions query
+ *
+ * The following are defines used for simplifying calling the mpalQuery variants
+ */
 
-/****************************************************************************\
-*       Macrofunctions query
-\****************************************************************************/
-
-/****************************************************************************\
-*
-* Function:     uint32 mpalQueryVersion(void);
-*
-* Description:  Gets the current version of MPAL
-*
-* Return:       Version number (0x1232 = 1.2.3b)
-*
-\****************************************************************************/
-
+/**
+ * Gets the current version of MPAL
+ *
+ * @returns	Version number (0x1232 = 1.2.3b)
+ */
 #define mpalQueryVersion()                              \
         (uint16)mpalQueryDWORD(MPQ_VERSION)
 
-
-
-/****************************************************************************\
-*
-* Function:     uint32 mpalQueryGlobalVar(LPSTR lpszVarName);
-*
-* Description:  Gets the numerical value of a global variable
-*
-* Input:        LPSTR lpszVarName       Nome della variabile (ASCIIZ)
-*
-* Return:       Valore della variabile
-*
-* Note:         This query was implemented for debugging. The program, 
-*				if well designed, should not need to access variables from 
-*				within the library.
-*
-\****************************************************************************/
-
+/**
+ * Gets the numerical value of a global variable
+ *
+ * @param lpszVarName		Nome della variabile (ASCIIZ)
+ * @returns		Global variable value
+ * @remarks		This query was implemented for debugging. The program, 
+ *				if well designed, should not need to access variables from 
+ *				within the library.
+ */
 #define mpalQueryGlobalVar(lpszVarName)                 \
         mpalQueryDWORD(MPQ_GLOBAL_VAR, (const char *)(lpszVarName))
 
 
-
-/****************************************************************************\
-*
-* Function:     HGLOBAL mpalQueryResource(uint32 dwResId);
-*
-* Description:  Provides access to a resource inside the .MPC file
-*
-* Input:        uint32 dwResId           ID della risorsa
-*
-* Return:       Handle to a memory area containing the resource, 
-*				ready for use.
-*
-\****************************************************************************/
-
+/**
+ * Provides access to a resource inside the .MPC file
+ *
+ * @param dwResId			Resource Id
+ * @returns		Handle to a memory area containing the resource,  ready for use.
+ */
 #define mpalQueryResource(dwResId)                      \
         mpalQueryHANDLE(MPQ_RESOURCE, (uint32)(dwResId))
 
 
-
-/****************************************************************************\
-*
-* Function:     LPSTR mpalQueryMessage(uint32 nMsg);
-*
-* Description:  Returns a message.
-*
-* Input:        uint32 nMsg               Message number
-*
-* Return:       ASCIIZ message
-*
-* Note:         The returned pointer must be freed with GlobalFree()
+/**
+ * Returns a message.
+ *
+ * @param nMsg				Message number
+ * @returns		ASCIIZ message
+ * @remarks		The returned pointer must be freed via the memory manager
 *				after use. The message will be in ASCIIZ format.
-*
-\****************************************************************************/
-
+*/
 #define mpalQueryMessage(nMsg)                          \
         (LPSTR)mpalQueryHANDLE(MPQ_MESSAGE, (uint32)(nMsg))
 
 
-
-/****************************************************************************\
-*
-* Function:     HGLOBAL mpalQueryLocationImage(uint32 nLoc);
-*
-* Description:  Provides a image image
-*
-* Input:        uint32 nLoc              Locazion number
-*
-* Return:       Returns a picture handle
-*
-\****************************************************************************/
-
+/**
+ * Provides a location image
+ * @return		Returns a picture handle
+ */
 #define mpalQueryLocationImage(nLoc)                    \
         mpalQueryHANDLE(MPQ_LOCATION_IMAGE, (uint32)(nLoc))
 
 
-
-/****************************************************************************\
-*
-* Function:     uint32 mpalQueryLocationSize(uint32 nLoc, uint32 dwCoord);
-*
-* Description:  Request the x or y size of a location in pixels
-*
-* Input:        uint32 nLoc              Location number
-*               uint32 dwCoord           MPQ_Xr o MPQ_Y
-*
-* Return:       Size
-*
-\****************************************************************************/
-
+/**
+ * Request the x or y size of a location in pixels
+ *
+ * @param nLoc				Location number
+ * @param dwCoord           MPQ_X or MPQ_Y coordinate to retrieve
+ * @returns		Size
+ */
 #define mpalQueryLocationSize(nLoc,dwCoord)             \
         mpalQueryDWORD(MPQ_LOCATION_SIZE,(uint32)(nLoc),(uint32)(dwCoord))
 
 
-
-/****************************************************************************\
-*
-* Function:     uint32 * mpalQueryItemList(uint32 nLoc);
-*
-* Description:  Provides the list of objects in the lease.
-*
-* Input:        uint32 nLoc              Location number
-*
-* Return:       List of objects (accessible by Item [0], Item [1], etc.)
-*
-\****************************************************************************/
-// TODO: Check if the results of this are endian safe
+/**
+ * Provides the list of objects in a location.
+ *
+ * @param nLoc              Location number
+ * @returns					List of objects (accessible by Item [0], Item [1], etc.)
+ */
+// TODO: Determine if this is endian safe
 #define mpalQueryItemList(nLoc)                         \
         (uint32 *)mpalQueryHANDLE(MPQ_ITEM_LIST,(uint32)(nLoc))
 
 
-
-/****************************************************************************\
-*
-* Function:     LPBKGANIM mpalQueryItemData(uint32 nItem);
-*
-* Description:  Provides information on an item
-*e
-* Input:        uint32 nItem             Item number
-*
-* Return:       structure filled with requested information
-*
-\****************************************************************************/
-
+/**
+ * Provides information on an item
+ *
+ * @param nItem             Item number
+ * @returns		Structure filled with requested information
+ */
 #define mpalQueryItemData(nItem)                          \
         (LPITEM)mpalQueryHANDLE(MPQ_ITEM_DATA,(uint32)(nItem))
 
 
-
-/****************************************************************************\
-*
-* Function:     uint32 mpalQueryItemPattern(uint32 nItem);
-*
-* Description:  Provides the current pattern of an item
-*
-* Input:        uint32 nItem             Item number
-*
-* Return:       Number of animation patterns to be executed.
-*
-* Note:         By default, the pattern of 0 indicates that we should 
-*				do nothing.
-*
-\****************************************************************************/
-
+/**
+ * Provides the current pattern of an item
+ *
+ * @param nItem             Item number
+ * @returns		Number of animation patterns to be executed.
+ * @remarks		By default, the pattern of 0 indicates that we should do nothing.
+ */
 #define mpalQueryItemPattern(nItem)                  \
         mpalQueryDWORD(MPQ_ITEM_PATTERN,(uint32)(nItem))
 
 
-
-/****************************************************************************\
-*
-* Function:     bool mpalQueryItemIsActive(uint32 nItem);
-*
-* Description:  Returns true if an item is active
-*
-* Input:        uint32 nItem             Item number
-*
-* Return:       TRUE if the item is active, FALSE otherwise
-*
-\****************************************************************************/
-
+/**
+ * Returns true if an item is active
+ *
+ * @param nItem             Item number
+ * @returns		TRUE if the item is active, FALSE otherwise
+ */
 #define mpalQueryItemIsActive(nItem)                  \
         (bool)mpalQueryDWORD(MPQ_ITEM_IS_ACTIVE,(uint32)(nItem))
 
 
-/****************************************************************************\
-*
-* Function:     void mpalQueryItemName(uint32 nItem, LPSTR lpszName);
-*
-* Description:  Returns the name of an item
-*
-* Input:        uint32 nItem             Item number
-*               LPSTR lpszName          Pointer to a buffer of at least 33 bytes
-*                                       that will be filled with the name
-*
-* Note:         If the item is not active (ie. if its status or number
-*				is less than or equal to 0), the string will be empty.
-*
-\****************************************************************************/
-
+/**
+ * Returns the name of an item
+ *
+ * @param nItem             Item number
+ * @param lpszName          Pointer to a buffer of at least 33 bytes
+ *                          that will be filled with the name
+ * @remarks		If the item is not active (ie. if its status or number
+ *				is less than or equal to 0), the string will be empty.
+ */
 #define mpalQueryItemName(nItem, lpszName)             \
         mpalQueryHANDLE(MPQ_ITEM_NAME,(uint32)(nItem), (LPSTR)(lpszName))
 
 
-
-/****************************************************************************\
-*
-* Function:     LPSTR mpalQueryDialogPeriod(uint32 nDialog, uint32 nPeriod);
-*
-* Description:  Returns a sentence of dialog.
-*
-* Input:        uint32 nDialog           Dialog number
-*               uint32 nPeriod           Number of words
-*
-* Return:       A pointer to the string of words, or NULL on failure.
-*
-* Note:         The string must be freed after use by GlobalFree ().
-*
-*               Unlike normal messages, the sentences of dialogue
-*				are formed by a single string terminated with 0.
-*
-\****************************************************************************/
-
+/**
+ * Returns a sentence of dialog.
+ *
+ * @param nDialog           Dialog number
+ * @param nPeriod           Number of words
+ * @returns		A pointer to the string of words, or NULL on failure.
+ * @remarks		The string must be freed after use using the memory manager.
+ * Unlike normal messages, the sentences of dialogue are formed by a single 
+ * string terminated with 0.
+ */
 #define mpalQueryDialogPeriod(nPeriod)                  \
         (LPSTR)mpalQueryHANDLE(MPQ_DIALOG_PERIOD, (uint32)(nPeriod))
 
 
-
-/****************************************************************************\
-*
-* Function:     int mpalQueryDialogWaitForChoice(void);
-*
-* Description:  Wait until the moment in which the need is signaled 
-*				to make a choice by the user.
-*
-* Return:       Number of choice to be made, or -1 if the dialogue is finished.
-*
-\****************************************************************************/
-
+/**
+ * Wait until the moment in which the need is signaled to make a choice by the user.
+ * @returns		Number of choice to be made, or -1 if the dialogue is finished.
+ */
 #define mpalQueryDialogWaitForChoice(dwRet)                  \
         CORO_INVOKE_2(mpalQueryCORO, MPQ_DIALOG_WAITFORCHOICE, dwRet)
 
-/****************************************************************************\
-*
-* Function:     uint32 * mpalQueryDialogSelectList(uint32 nChoice);
-*
-* Description:  Requires a list of various options for some choice within 
-*				the current dialog.
-
-* Input:        uint32 nChoice           Choice number
-*
-* Return:       A pointer to an array containing the data matched to each option.
-*
-* Note:         The figure 'a uint32 specified in the source to which MPAL
-*				You can 'assign meaning that the more' suits.
-*
-*               The pointer msut be freed after use by GlobalFree().
-*
-\****************************************************************************/
 
+/**
+ * Requires a list of various options for some choice within the current dialog.
+ *
+ * @param nChoice			Choice number
+ * @returns		A pointer to an array containing the data matched to each option.
+ * @remarks		The figure 'a uint32 specified in the source to which MPAL
+ * You can assign meaning that the more' suits.
+ * The pointer msut be freed after use using the memory memory.
+ */
 #define mpalQueryDialogSelectList(nChoice)              \
         (uint32 *)mpalQueryHANDLE(MPQ_DIALOG_SELECTLIST,(uint32)(nChoice))
 
 
-
-/****************************************************************************\
-*
-* Function:     bool mpalQueryDialogSelection(uint32 nChoice, uint32 dwData);
-*
-* Description:  Warns the library that the user has selected, in a certain 
-*				choice of the current dialog, corresponding option
-*				at a certain given.
-*
-* Input:        uint32 nChoice           Choice number of the choice that 
-*										was in progress
-*               uint32 dwData            Option that was selected by the user.
-*
-* Return:       TRUE if all OK, FALSE on failure.
-*
-* Note:         After execution of this query, MPAL continue 
-* Groups according to the execution of the dialogue. And necessary so the game 
-* remains on hold again for another  Chosen by mpalQueryDialogWaitForChoice ().
-*
-\****************************************************************************/
-
+/**
+ * Warns the library that the user has selected, in a certain choice of the current dialog, 
+ * corresponding option at a certain given.
+ *
+ * @param nChoice			Choice number of the choice that was in progress
+ * @param dwData			Option that was selected by the user.
+ * @returns		TRUE if all OK, FALSE on failure.
+ * @remarks		After execution of this query, MPAL continue 
+ * Groups according to the execution of the dialogue. And necessary so the game 
+ * remains on hold again for another chosen by mpalQueryDialogWaitForChoice ().
+ */
 #define mpalQueryDialogSelection(nChoice,dwData)        \
         (bool)mpalQueryDWORD(MPQ_DIALOG_SELECTION,(uint32)(nChoice),(uint32)(dwData))
 
@@ -526,245 +399,169 @@ typedef LPITEMIRQFUNCTION* LPLPITEMIRQFUNCTION;
         mpalQueryDWORD(MPQ_DIALOG_SELECTION,(uint32)(nChoice),(uint32)(dwData))
 
 
-/****************************************************************************\
-*
-* Function:     HANDLE mpalQueryDoAction(uint32 nAction, uint32 nItem,
-*                 uint32 dwParam);
-*
-* Description:  Warns the library an action was performed on a Object. 
-* The library will call 'custom functions, if necessary.
-*
-* Input:        uint32 nAction           Action number
-*               uint32 nItem             Item number
-*               uint32 dwParam           Action parameter
-*
-* Return:       Handle to the thread that is performing the action, or
-*				CORO_INVALID_PID_VALUE if the action is not 'defined for 
-*				the item, or the item and 'off.
-*
-* Note:         The parameter is used primarily to implement actions 
-* as "U.S." involving two objects together. The action will be executed only
-* if the item is active, ie if its status is a positive number greater than 0.
-*
-\****************************************************************************/
-
+/**
+ * Warns the library an action was performed on a Object. 
+ * The library will call custom functions, if necessary.
+ *
+ * @param nAction			Action number
+ * @param nItem				Item number
+ * @param dwParam			Action parameter
+ * @returns		Handle to the thread that is performing the action, or CORO_INVALID_PID_VALUE 
+ * if the action is not defined for the item, or the item is inactive.
+ * @remarks		The parameter is used primarily to implement actions 
+ * as "U.S." involving two objects together. The action will be executed only
+ * if the item is active, ie if its status is a positive number greater than 0.
+ */
 #define mpalQueryDoAction(nAction, nItem, dwParam)      \
         mpalQueryDWORD(MPQ_DO_ACTION, (uint32)(nAction), (uint32)(nItem), (uint32)(dwParam))
 
 
-
-/****************************************************************************\
-*
-* Function:     HANDLE mpalQueryDoDialog(uint32 nDialog, uint32 nGroup);
-*
-* Description:  Warns the library a dialogue was required.
-*
-* Input:        uint32 nDialog           Dialog number
-*               uint32 nGroup            Group number to use
-*
-* Return:       Handle to the thread that is running the box, or
-*				CORO_INVALID_PID_VALUE if the dialogue does not exist.
-*
-\****************************************************************************/
-
+/**
+ * Warns the library a dialogue was required.
+ *
+ * @param nDialog			Dialog number
+ * @param nGroup			Group number to use
+ * @returns		Handle to the thread that is running the box, or
+ * CORO_INVALID_PID_VALUE if the dialogue does not exist.
+ */
 #define mpalQueryDoDialog(nDialog,nGroup)               \
         mpalQueryDWORD(MPQ_DO_DIALOG, (uint32)(nDialog),(uint32)(nGroup))
 
 
-/****************************************************************************\
-*       Functions exported to the main game
-\****************************************************************************/
-
+/**
+ * @defgroup Functions exported to the main game
+ */
 
-/****************************************************************************\
-*
-* Function:     bool mpalInit(LPSTR lpszMpcFileName, LPSTR lpszMprFileName,
-*                 LPLPCUSTOMFUNCTION lplpcfArray);
-*
-* Description:  Initializes the MPAL library, and opens an .MPC file, which
-*				will be 'used for all queries
-*
-* Input:        LPSTR lpszMpcFileName   Name of the .MPC file, including extension
-*               LPSTR lpszMprFileName   Name of the .MPR file, including extension
-*               LPLPCUSTOMFUNCTION		Array of pointers to custom functions
-*
-* Return:       TRUE if all OK, FALSE on failure
-*
-\****************************************************************************/
 
+/**
+ * Initializes the MPAL library, and opens an .MPC file, which will be 'used for all queries
+ * @param lpszMpcFileName	Name of the .MPC file, including extension
+ * @param lpszMprFileName	Name of the .MPR file, including extension
+ * @param lplpcfArray		Array of pointers to custom functions
+ * @returns		TRUE if all OK, FALSE on failure
+ */
 bool mpalInit(const char *lpszFileName, const char *lpszMprFileName,
 					 LPLPCUSTOMFUNCTION lplpcfArray, Common::String *lpcfStrings);
 
 
-
-/****************************************************************************\
-*
-* Function:     uint32 mpalQuery(uint16 wQueryType, ...);
-*
-* Description:  This is the general function to communicate with the library,
-*				To request information about what is in the .MPC file
-*
-* Input:        uint16 wQueryType       Type of query. The list is in
-*										the QueryTypes enum.
-*
-* Return:       4 bytes depending on the type of query
-*
-* Note:         I _strongly_ recommended to use macros defined above to use 
-*				the query, since it helps avoid any unpleasant bugs due to 
-*				forgeting parameters.
-*
-\****************************************************************************/
-
-typedef void *HANDLE;
-
+/**
+ * This is a general function to communicate with the library, to request information
+ * about what is in the .MPC file
+ *
+ * @param wQueryType		Type of query. The list is in the QueryTypes enum.
+ * @returns		4 bytes depending on the type of query
+ * @remarks		This is the specialised version of the original single mpalQuery
+ * method that returns numeric results.
+ */
 uint32 mpalQueryDWORD(uint16 wQueryType, ...);
 
+/**
+ * This is a general function to communicate with the library, to request information
+ * about what is in the .MPC file
+ *
+ * @param wQueryType		Type of query. The list is in the QueryTypes enum.
+ * @returns		4 bytes depending on the type of query
+ * @remarks		This is the specialised version of the original single mpalQuery
+ * method that returns a pointer or handle.
+ */
 HANDLE mpalQueryHANDLE(uint16 wQueryType, ...);
 
+/**
+ * This is a general function to communicate with the library, to request information
+ * about what is in the .MPC file
+ *
+ * @param wQueryType		Type of query. The list is in the QueryTypes enum.
+ * @returns		4 bytes depending on the type of query
+ * @remarks		This is the specialised version of the original single mpalQuery
+ * method that needs to run within a co-routine context.
+ */
 void mpalQueryCORO(CORO_PARAM, uint16 wQueryType, uint32 *dwRet, ...);
 
-/****************************************************************************\
-*
-* Function:     bool mpalExecuteScript(int nScript);
-*
-* Description:  Execute a script. The script runs on multitasking by a thread.
-*
-* Input:        int nScript             Script number to run
-*
-* Return:       TRUE if the script 'was launched, FALSE on failure
-*
-\****************************************************************************/
 
+/**
+ * Execute a script. The script runs on multitasking by a thread.
+ *
+ * @param nScript			Script number to run
+ * @returns		TRUE if the script 'was launched, FALSE on failure
+ */
 bool mpalExecuteScript(int nScript);
 
 
-
-/****************************************************************************\
-*
-* Function:     uint32 mpalGetError(void);
-*
-* Description:  Returns the current MPAL error code
-*
-* Return:       Error code
-*
-\****************************************************************************/
-
+/**
+ * Returns the current MPAL error code
+ *
+ * @returns		Error code
+ */
 uint32 mpalGetError(void);
 
 
-
-/****************************************************************************\
-*
-* Function:     void mpalInstallItemIrq(LPITEMIRQFUNCTION lpiifCustom);
-*
-* Description:  Install a custom routine That will be called by MPAL
-*				every time the pattern of an item has-been changed.
-*
-* Input:        LPITEMIRQFUNCTION lpiifCustom   Custom function to install
-*
-\****************************************************************************/
-
+/**
+ * Install a custom routine That will be called by MPAL every time the pattern 
+ * of an item has been changed.
+ *
+ * @param lpiifCustom		Custom function to install
+ */
 void mpalInstallItemIrq(LPITEMIRQFUNCTION lpiifCustom);
 
 
-/****************************************************************************\
-*
-* Function:     bool mpalStartIdlePoll(int nLoc);
-*
-* Description:  Process the idle actions of the items on one location.
-*
-* Input:        int nLoc                Number of the location whose items
-*                                       must be processed for idle actions.
-*
-* Return:       TRUE if all OK, and FALSE if it exceeded the maximum limit.
-*
-* Note:         The maximum number of locations that can be polled
-*				simultaneously is defined defined by MAXPOLLINGFUNCIONS
-*
-\****************************************************************************/
-
+/**
+ * Process the idle actions of the items on one location.
+ *
+ * @param nLoc				Number of the location whose items must be processed 
+ * for idle actions.
+ * @returns		TRUE if all OK, and FALSE if it exceeded the maximum limit.
+ * @remarks		The maximum number of locations that can be polled
+ * simultaneously is defined defined by MAXPOLLINGFUNCIONS
+ */
 bool mpalStartIdlePoll(int nLoc);
 
 
-/****************************************************************************\
-*
-* Function:     bool mpalEndIdlePoll(int nLoc);
-*
-* Description:  Stop processing the idle actions of the items on one location.
-*
-* Input:        int nLoc                Number of the location
-*
-* Return:       TRUE if all OK, FALSE if the specified location was not
-*				in the process of polling
-*
-\****************************************************************************/
-
+/**
+ * Stop processing the idle actions of the items on one location.
+ *
+ * @param nLo				Number of the location
+ * @returns		TRUE if all OK, FALSE if the specified location was not
+ * in the process of polling
+ */
 void mpalEndIdlePoll(CORO_PARAM, int nLoc, bool *result);
 
 
-/****************************************************************************\
-*
-* Function:     int mpalLoadState(LPBYTE buf);
-*
-* Description:  Load a save state from a buffer. 
-*
-* Input:				LPBYTE buf		Buffer where to store the state
-*
-*	Return:				Length of the state in bytes
-*
-\****************************************************************************/
-
+/**
+ * Load a save state from a buffer.
+ *
+ * @param buf				Buffer where to store the state
+ * @returns		Length of the state buffer in bytes
+ */
 int mpalLoadState(byte *buf);
 
 
-
-/****************************************************************************\
-*
-* Function:     void mpalSaveState(LPBYTE buf);
-*
-* Description:  Store the save state into a buffer. The buffer must be
-*				length at least the size specified with mpalGetSaveStateSize
-*
-* Input:		LPBYTE buf				Buffer where to store the state
-*
-\****************************************************************************/
-
+/**
+ * Store the save state into a buffer. The buffer must be
+ * length at least the size specified with mpalGetSaveStateSize
+ *
+ * @param buf				Buffer where to store the state
+ */
 void mpalSaveState(byte *buf);
 
 
-
-/****************************************************************************\
-*
-* Function:     int mpalGetSaveStateSize(void);
-*
-* Description:  Acquire the length of a save state
-*
-* Return:       Length in bytes
-*
-\****************************************************************************/
-
+/**
+ * Retrieve the length of a save state
+ *
+ * @returns		Length in bytes
+ */
 int mpalGetSaveStateSize(void);
 
 
-/****************************************************************************\
-*
-* Function:     void LockVar(void);
-*
-* Description:  Locka le variabili per accederci
-*
-\****************************************************************************/
-
-extern void LockVar(void);
+/**
+ * Locks the variables for access
+ */
+void LockVar(void);
 
-/****************************************************************************\
-*
-* Function:     void UnlockVar(void);
-*
-* Description:  Unlocka le variabili dopo l'uso
-*
-\****************************************************************************/
 
-extern void UnlockVar(void);
+/**
+ * Unlocks variables after use
+ */
+void UnlockVar(void);
 
 } // end of namespace MPAL