Patch

svn-id: r41647

7 files changed, 547 insertions, 426 deletions

diff --git a/engines/sci/engine/gc.h b/engines/sci/engine/gc.h
index e6fa737aaf..9f9347ca18 100644
--- a/engines/sci/engine/gc.h
+++ b/engines/sci/engine/gc.h
@@ -45,19 +45,23 @@ struct reg_t_Hash {
 	}
 };
 
-// The reg_t_hash_map is actually really a hashset
+/*
+ * The reg_t_hash_map is actually really a hashset
+ */
 typedef Common::HashMap<reg_t, bool, reg_t_Hash, reg_t_EqualTo> reg_t_hash_map;
 
+/**
+ * Finds all used references and normalises them to their memory addresses
+ * @param s The state to gather all information from
+ * @return A hash map containing entries for all used references
+ */
 reg_t_hash_map *find_all_used_references(EngineState *s);
-/* Finds all used references and normalises them to their memory addresses
-** Parameters: (EngineState *) s: The state to gather all information from
-** Returns   : (reg_t_hash_map *) A hash map containing entries for all used references
-*/
 
+/**
+ * Runs garbage collection on the current system state
+ * @param s The state in which we should gc
+ */
 void run_gc(EngineState *s);
-/* Runs garbage collection on the current system state
-** Parameters: (EngineState *) s: The state in which we should gc
-*/
 
 } // End of namespace Sci
 
diff --git a/engines/sci/engine/intmap.h b/engines/sci/engine/intmap.h
index 2cb4f69f1f..1c028975a9 100644
--- a/engines/sci/engine/intmap.h
+++ b/engines/sci/engine/intmap.h
@@ -83,7 +83,7 @@ public:
 
 	/**
 	 * Checks whether a key is in the map, adds it if neccessary.
-	 * @param value		The key to check for/add
+	 * @param key		The key to check for/add
 	 * @param add		Whether to add the key if it's not in there
 	 * @param was_added	Set to non-zero if and only if the key is new, ignored if NULL.
 	 * @return The new (or old) index, or -1 if add was zero and
@@ -91,6 +91,11 @@ public:
 	 */
 	int checkKey(int key, bool add, bool *wasAdded = 0);
 
+	/**
+	 * Looks up a key in the map
+	 * @parmam key The key to look for
+	 * @return The value or -1 if not found 
+	 */
 	int lookupKey(int key) const;
 
 
diff --git a/engines/sci/engine/kernel.h b/engines/sci/engine/kernel.h
index 27d9df059d..46913a5b39 100644
--- a/engines/sci/engine/kernel.h
+++ b/engines/sci/engine/kernel.h
@@ -69,16 +69,17 @@ public:
 	uint getKernelNamesSize() const { return _kernelNames.size(); }
 	const Common::String &getKernelName(uint number) const { return _kernelNames[number]; }
 
-	/* Determines the selector ID of a selector by its name
-	**             (const char *) selectorName: Name of the selector to look up
-	** Returns   : (int) The appropriate selector ID, or -1 on error
-	*/
+	/**
+	 * Determines the selector ID of a selector by its name
+	 * @param selectorName Name of the selector to look up
+	 * @return The appropriate selector ID, or -1 on error
+	 */
 	int findSelector(const char *selectorName) const;
 
-	/* Detects whether a particular kernel function is required in the game
-	**             (const char *) functionName: The name of the desired kernel function
-	** Returns   : (bool) true if the kernel function is listed in the kernel table,
-	**                   false otherwise
+	/**
+	 * Detects whether a particular kernel function is required in the game
+	 * @param functionName The name of the desired kernel function
+	 * @return True if the kernel function is listed in the kernel table, false otherwise
 	*/
 	bool hasKernelFunction(const char *functionName) const;
 
@@ -104,18 +105,18 @@ private:
 
 	/**
 	* Loads the kernel selector names.
-	* Returns true upon success, false otherwise.
+	* @return True upon success, false otherwise.
 	*/
 	bool loadSelectorNames(bool isOldSci0);
 
-	/* Maps special selectors
-	** Returns   : (void)
-	*/
+	/**
+	 * Maps special selectors
+	 */
 	void mapSelectors();
 
-	/* Maps kernel functions
-	** Returns   : (void)
-	*/
+	/**
+	 * Maps kernel functions
+	 */
 	void mapFunctions();
 
 	/**
@@ -127,8 +128,10 @@ private:
 	ResourceManager *_resmgr;
 
 	// Kernel-related lists
-	// List of opcodes, loaded from vocab.998. This list is only used for debugging
-	// purposes, as we hardcode the list of opcodes in the sci_opcodes enum (script.h)
+	/**
+	 * List of opcodes, loaded from vocab.998. This list is only used for debugging
+	 * purposes, as we hardcode the list of opcodes in the sci_opcodes enum (script.h)
+	 */
 	Common::Array<opcode> _opcodes;
 	Common::StringList _selectorNames;
 	Common::StringList _kernelNames;
@@ -178,61 +181,62 @@ int invoke_selector(EngineState *s, reg_t object, int selector_id, SelectorInvoc
 
 
 /******************** Text functionality ********************/
+/**
+ * Looks up text referenced by scripts
+ * SCI uses two values to reference to text: An address, and an index. The address
+ * determines whether the text should be read from a resource file, or from the heap,
+ * while the index either refers to the number of the string in the specified source,
+ * or to a relative position inside the text.
+ *
+ * @param s The current state
+ * @param address The address to look up
+ * @param index The relative index
+ * @return The referenced text, or NULL on error.
+ */
 char *kernel_lookup_text(EngineState *s, reg_t address, int index);
-/* Looks up text referenced by scripts
-** Parameters: (EngineState *s): The current state
-**             (reg_t) address: The address to look up
-**             (int) index: The relative index
-** Returns   : (char *): The referenced text, or NULL on error.
-** SCI uses two values to reference to text: An address, and an index. The address
-** determines whether the text should be read from a resource file, or from the heap,
-** while the index either refers to the number of the string in the specified source,
-** or to a relative position inside the text.
-*/
 
 
 /******************** Debug functionality ********************/
-
+/**
+ * Checks whether a heap address contains an object
+ * @param s The current state
+ * @parm obj The address to check
+ * @return True if it is an object, false otherwise
+ */
 bool is_object(EngineState *s, reg_t obj);
-/* Checks whether a heap address contains an object
-** Parameters: (EngineState *) s: The current state
-**             (reg_t) obj: The address to check
-** Returns   : (bool) true if it is an object, false otherwise
-*/
 
 /******************** Kernel function parameter macros ********************/
 
 /* Returns the parameter value or (alt) if not enough parameters were supplied */
-
+/**
+ * Dereferences a heap pointer
+ * @param s The state to operate on
+ * @param pointer The pointer to dereference
+ * @parm entries The number of values expected (for checking; use 0 for strings)
+ * @return A physical reference to the address pointed to, or NULL on error or
+ * if not enugh entries were available.
+ * reg_t dereferenciation also assures alignedness of data.
+ */
 reg_t *kernel_dereference_reg_pointer(EngineState *s, reg_t pointer, int entries);
 byte *kernel_dereference_bulk_pointer(EngineState *s, reg_t pointer, int entries);
 #define kernel_dereference_char_pointer(state, pointer, entries) (char*)kernel_dereference_bulk_pointer(state, pointer, entries)
-/* Dereferences a heap pointer
-** Parameters: (EngineState *) s: The state to operate on
-**             (reg_t ) pointer: The pointer to dereference
-**             (int) entries: The number of values expected (for checking)
-**                            (use 0 for strings)
-** Returns   : (reg_t/char *): A physical reference to the address pointed
-**                        to, or NULL on error or if not enugh entries
-**                        were available
-** reg_t dereferenciation also assures alignedness of data.
-*/
 
 /******************** Priority macros/functions ********************/
-
+/**
+ * Finds the position of the priority band specified
+ * Parameters: (EngineState *) s: State to search in
+ * (int) band: Band to look for
+ * Returns   : (int) Offset at which the band starts
+ */
 int _find_priority_band(EngineState *s, int band);
-/* Finds the position of the priority band specified
-** Parameters: (EngineState *) s: State to search in
-**             (int) band: Band to look for
-** Returns   : (int) Offset at which the band starts
-*/
 
+/**
+ * Does the opposite of _find_priority_band
+ * @param s Engine state
+ * @param y Coordinate to check
+ * @return The priority band y belongs to
+ */
 int _find_view_priority(EngineState *s, int y);
-/* Does the opposite of _find_priority_band
-** Parameters: (EngineState *) s: State
-**             (int) y: Coordinate to check
-** Returns   : (int) The priority band y belongs to
-*/
 
 #define SCI0_VIEW_PRIORITY_14_ZONES(y) (((y) < s->priority_first)? 0 : (((y) >= s->priority_last)? 14 : 1\
 	+ ((((y) - s->priority_first) * 14) / (s->priority_last - s->priority_first))))
@@ -249,50 +253,59 @@ int _find_view_priority(EngineState *s, int y);
 
 
 /******************** Dynamic view list functions ********************/
-
+/**
+ * Determines the base rectangle of the specified view object
+ * @param s The state to use
+ * @param object The object to set
+ * @return The absolute base rectangle
+ */
 Common::Rect set_base(EngineState *s, reg_t object);
-/* Determines the base rectangle of the specified view object
-** Parameters: (EngineState *) s: The state to use
-**             (reg_t) object: The object to set
-** Returns   : (abs_rect) The absolute base rectangle
-*/
 
+/**
+ * Determines the now-seen rectangle of a view object
+ * @param s The state to use
+ * @param object The object to check
+ * @param clip Flag to determine wheter priority band clipping 
+ * should be performed
+ * @return The absolute rectangle describing the now-seen area.
+ */
 extern Common::Rect get_nsrect(EngineState *s, reg_t object, byte clip);
-/* Determines the now-seen rectangle of a view object
-** Parameters: (EngineState *) s: The state to use
-**             (reg_t) object: The object to check
-**             (byte) clip: Flag to determine wheter priority band
-**                          clipping should be performed
-** Returns   : (abs_rect) The absolute rectangle describing the
-** now-seen area.
-*/
 
+/**
+ * Removes all views in anticipation of a new window or text 
+ */
 void _k_dyn_view_list_prepare_change(EngineState *s);
-/* Removes all views in anticipation of a new window or text */
+
+/**
+ * Redraws all views after a new window or text was added 
+ */
 void _k_dyn_view_list_accept_change(EngineState *s);
-/* Redraws all views after a new window or text was added */
 
 
 
 
 /******************** Misc functions ********************/
 
-void process_sound_events(EngineState *s); /* Get all sound events, apply their changes to the heap */
+/**
+ * Get all sound events, apply their changes to the heap 
+ */
+void process_sound_events(EngineState *s);
 
+/**
+ * Resolves an address into a list node
+ * @param s The state to operate on
+ * @param addr The address to resolve
+ * @return The list node referenced, or NULL on error
+ */
 Node *lookup_node(EngineState *s, reg_t addr);
-/* Resolves an address into a list node
-** Parameters: (EngineState *) s: The state to operate on
-**             (reg_t) addr: The address to resolve
-** Returns   : (Node *) The list node referenced, or NULL on error
-*/
-
 
+/**
+ * Resolves a list pointer to a list
+ * @param s The state to operate on
+ * @param addr The address to resolve
+ * @return The list referenced, or NULL on error
+ */
 List *lookup_list(EngineState *s, reg_t addr);
-/* Resolves a list pointer to a list
-** Parameters: (EngineState *) s: The state to operate on
-**             (reg_t) addr: The address to resolve
-** Returns   : (List *) The list referenced, or NULL on error
-*/
 
 
 /******************** Constants ********************/
diff --git a/engines/sci/engine/seg_manager.cpp b/engines/sci/engine/seg_manager.cpp
index 98fbd8bad7..2227167673 100644
--- a/engines/sci/engine/seg_manager.cpp
+++ b/engines/sci/engine/seg_manager.cpp
@@ -430,7 +430,7 @@ void SegManager::heapRelocate(reg_t block) {
 
 #define INST_LOOKUP_CLASS(id) ((id == 0xffff) ? NULL_REG : get_class_address(s, id, SCRIPT_GET_LOCK, NULL_REG))
 
-reg_t get_class_address(EngineState *s, int classnr, int lock, reg_t caller);
+reg_t get_class_address(EngineState *s, int classnr, SCRIPT_GET lock, reg_t caller);
 
 Object *SegManager::scriptObjInit0(EngineState *s, reg_t obj_pos) {
 	Object *obj;
diff --git a/engines/sci/engine/seg_manager.h b/engines/sci/engine/seg_manager.h
index dc91d60e69..a41d820014 100644
--- a/engines/sci/engine/seg_manager.h
+++ b/engines/sci/engine/seg_manager.h
@@ -45,29 +45,38 @@ namespace Sci {
 
 class SegManager : public Common::Serializable {
 public:
-	// Initialize the segment manager
+	/**
+	 * Initialize the segment manager
+	 */
 	SegManager(bool sci1_1);
 
-	// Deallocate all memory associated with the segment manager
+	/**
+	 * Deallocate all memory associated with the segment manager
+	 */
 	~SegManager();
 
 	virtual void saveLoadWithSerializer(Common::Serializer &ser);
 
 	// 1. Scripts
 
-	// Allocate a script into the segment manager
-	// Parameters: (int) script_nr: number of the script to load
-	//	       (state_t *) s: The state containing resource manager handlers to load the
-	//			      script data
-	// Returns   : (int) 0 on failure, 1 on success
-	//	       (int) *seg_id: The segment ID of the newly allocated segment, on success
+	/**
+	 * Allocate a script into the segment manager
+	 * @param s				The state containing resource manager 
+	 * 						handlers to load the script data
+	 * @param script_nr		The number of the script to load
+	 * @param seg_id		The segment ID of the newly allocated segment,
+	 * 						on success
+	 * @return				0 on failure, 1 on success
+	 */
 	Script *allocateScript(EngineState *s, int script_nr, SegmentId *seg_id);
 
 	// The script must then be initialised; see section (1b.), below.
 
-	// Forcefully deallocate a previously allocated script
-	// Parameters: (int) script_nr: number of the script to deallocate
-	// Returns   : (int) 1 on success, 0 on failure
+	/**
+	 * Forcefully deallocate a previously allocated script
+	 * @param script_nr		number of the script to deallocate
+	 * @return				1 on success, 0 on failure
+	 */
 	int deallocateScript(int script_nr);
 
 	/**
@@ -76,30 +85,40 @@ public:
 	 */
 	bool scriptIsLoaded(SegmentId seg);
 
-	// Validate whether the specified public function is exported by the script in the specified segment
-	// Parameters:	(int) pubfunct: Index of the function to validate
-	//		(int) seg: Segment ID of the script the check is to be performed for
-	// Returns   :  (uint16) 0 if the public function is invalid, its offset into the script's segment
-	//			 otherwise
+	/**
+	 * Validate whether the specified public function is exported by 
+	 * the script in the specified segment
+	 * @param pubfunct		Index of the function to validate
+	 * @param seg			Segment ID of the script the check is to 
+	 * 						be performed for
+	 * @return				NULL if the public function is invalid, its 
+	 * 						offset into the script's segment otherwise
+	 */
 	uint16 validateExportFunc(int pubfunct, SegmentId seg);
 
-	// Get the segment ID associated with a script number
-	// Parameters: (int) script_nr: Number of the script to look up
-	// Returns   : (int) The associated segment ID, or -1 if no matching segment exists
+	/**
+	 * Get the segment ID associated with a script number
+	 * @param script_nr		Number of the script to look up
+	 * @return				The associated segment ID, or -1 if no 
+	 * 						matching segment exists
+	 */
 	SegmentId segGet(int script_nr) const;
 
 	/**
-	 * Return a pointer to the specified script. If the id is invalid, does not refer
-	 * to a script or the script is not loaded, this will invoke error().
+	 * Return a pointer to the specified script.
+	 * If the id is invalid, does not refer to a script or the script is 
+	 * not loaded, this will invoke error().
 	 * @param seg	ID of the script segment to check for
-	 * @return pointer to the Script object
+	 * @return		A pointer to the Script object
 	 */
 	Script *getScript(SegmentId seg);
 
 	/**
-	 * Return a pointer to the specified script. If the id is invalid, does not refer
+	 * Return a pointer to the specified script.
+	 * If the id is invalid, does not refer to a script, or 
+	 * the script is not loaded, this will return NULL
 	 * @param seg	ID of the script segment to check for
-	 * @return pointer to the Script object, or NULL
+	 * @return		A pointer to the Script object, or NULL
 	 */
 	Script *getScriptIfLoaded(SegmentId seg);
 
@@ -112,51 +131,70 @@ public:
 	// to be used during script instantiation,
 	// i.e. loading and linking.
 
-	// Initializes a script's local variable block
-	// Parameters: (SegmentId) seg: Segment containing the script to initialize
-	//             (int) nr: Number of local variables to allocate
-	// All variables are initialized to zero.
+	/**
+	 * Initializes a script's local variable block
+	 * All variables are initialized to zero.
+	 * @param seg	Segment containing the script to initialize
+	 * @param nr	Number of local variables to allocate
+	 */
 	void scriptInitialiseLocalsZero(SegmentId seg, int nr);
 
-	// Initializes a script's local variable block according to a prototype
-	// Parameters: (reg_t) location: Location to initialize from
+	/**
+	 * Initializes a script's local variable block according to a prototype
+	 * @param location	Location to initialize from
+	 */
 	void scriptInitialiseLocals(reg_t location);
 
-	// Initializes an object within the segment manager
-	// Parameters: (reg_t) obj_pos: Location (segment, offset) of the object
-	// Returns   : (Object *) A newly created Object describing the object
-	// obj_pos must point to the beginning of the script/class block (as opposed
-	// to what the VM considers to be the object location)
-	// The corresponding Object is stored within the relevant script.
+	/**
+	 * Initializes an object within the segment manager
+	 * @param obj_pos	Location (segment, offset) of the object. It must
+	 * 					point to the beginning of the script/class block 
+	 * 					(as opposed to what the VM considers to be the 
+	 * 					object location)
+	 * @returns			A newly created Object describing the object,
+	 * 					stored within the relevant script
+	 */
 	Object *scriptObjInit(EngineState *s, reg_t obj_pos);
 
-	// Informs the segment manager that a code block must be relocated
-	// Parameters: (reg_t) location: Start of block to relocate
+	/**
+	 * Informs the segment manager that a code block must be relocated
+	 * @param location	Start of block to relocate
+	 */
 	void scriptAddCodeBlock(reg_t location);
 
-	// Tells the segment manager whether exports are wide (32-bit) or not.
-	// Parameters: (int) flag: 1 if exports are wide, 0 otherwise
+	/**
+	 * Tells the segment manager whether exports are wide (32-bit) or not.
+	 * @param flag	1 if exports are wide, 0 otherwise
+	 */
 	void setExportWidth(int flag);
 
-	// Processes a relocation block witin a script
-	// Parameters: (reg_t) obj_pos: Location (segment, offset) of the block
-	// Returns   : (Object *) Location of the relocation block
-	// This function is idempotent, but it must only be called after all
-	// objects have been instantiated, or a run-time error will occur.
+	/**
+	 * Processes a relocation block witin a script
+	 *  This function is idempotent, but it must only be called after all
+	 *  objects have been instantiated, or a run-time error will occur.
+	 * @param obj_pos	Location (segment, offset) of the block
+	 * @return			Location of the relocation block
+	 */
 	void scriptRelocate(reg_t block);
 
-	// Determines whether the script referenced by the indicated segment is marked as being deleted.
-	// Parameters: (SegmentId) Segment ID of the script to investigate
-	// Returns   : (int) 1 iff seg points to a script and the segment is deleted, 0 otherwise
-	// Will return 0 when applied to an invalid or non-script seg.
+	/**
+	 * Determines whether the script referenced by the indicated segment 
+	 * is marked as being deleted.
+	 * Will return 0 when applied to an invalid or non-script seg.
+	 * @param seg	Segment ID of the script to investigate
+	 * @return		1 iff seg points to a script and the segment is 
+	 * 				deleted, 0 otherwise
+	 */
 	bool scriptIsMarkedAsDeleted(SegmentId seg);
 
 
 	// 2. Clones
 
-	// Allocate a fresh clone
-	// Returns : (Clone*): Reference to the memory allocated for the clone
-	//           (reg_t) *addr: The offset of the freshly allocated clone
+	/**
+	 * Allocate a fresh clone
+	 * @param addr The offset of the freshly allocated clone
+	 * @return	Reference to the memory allocated for the clone
+	 */
 	Clone *alloc_Clone(reg_t *addr);
 
 
@@ -166,76 +204,96 @@ public:
 
 	// 4. Stack
 
-	// Allocates a data stack
-	// Parameters: (int) size: Number of stack entries to reserve
-	// Returns   : (DataStack *): The physical stack
-	//             (SegmentId) segid: Segment ID of the stack
+	/**
+	 * Allocates a data stack
+	 * @param size	Number of stack entries to reserve
+	 * @param segid	Segment ID of the stack
+	 * @return		The physical stack
+	 */
 	DataStack *allocateStack(int size, SegmentId *segid);
 
 
 	// 5. System Strings
 
-	// Allocates a system string table
-	// Returns   : (DataStack *): The physical stack
-	//             (SegmentId) segid: Segment ID of the stack
-	// See also sys_string_acquire();
+	/**
+	 * Allocates a system string table
+	 * See also sys_string_acquire();
+	 * @param[in] segid	Segment ID of the stack
+	 * @returns			The physical stack
+	 */            
 	SystemStrings *allocateSysStrings(SegmentId *segid);
 
 
 	// 5. System Strings
 
-	// Allocates a string fragments segment
-	// Returns   : (SegmentId): Segment ID to use for string fragments
-	// See also stringfrag.h
+	/**
+	 * Allocates a string fragments segment
+	 * See also stringfrag.h
+	 * @return	Segment ID to use for string fragments
+	 */
 	SegmentId allocateStringFrags();
 
 
 	// 6, 7. Lists and Nodes
 
-	// Allocate a fresh list
-	// Returns : (listY_t*): Reference to the memory allocated for the list
-	//           (reg_t) *addr: The offset of the freshly allocated list
+	/**
+	 * Allocate a fresh list
+	 * @param[in] addr	The offset of the freshly allocated list
+	 * @return			Reference to the memory allocated for the list
+	 */
 	List *alloc_List(reg_t *addr);
 
-	// Allocate a fresh node
-	// Returns : (node_t*): Reference to the memory allocated for the node
-	//           (reg_t) *addr: The offset of the freshly allocated node
+	/**
+	 * Allocate a fresh node
+	 * @param[in] addr	The offset of the freshly allocated node
+	 * @return			Reference to the memory allocated for the node
+	 */
 	Node *alloc_Node(reg_t *addr);
 
 
 	// 8. Hunk Memory
 
-	// Allocate a fresh chunk of the hunk
-	// Parameters: (int) size: Number of bytes to allocate for the hunk entry
-	//             (const char *) hunk_type: A descriptive string for the hunk entry,
-	//				for debugging purposes
-	// Returns   : (Hunk *): Reference to the memory allocated for the hunk piece
-	//             (reg_t) *addr: The offset of the freshly allocated hunk entry
+	/**
+	 * Allocate a fresh chunk of the hunk
+	 * @param[in] size		Number of bytes to allocate for the hunk entry
+	 * @param[in] hunk_type	A descriptive string for the hunk entry, for 
+	 *	 					debugging purposes
+	 * @param[out] addr		The offset of the freshly allocated hunk entry
+	 * @return				Reference to the memory allocated for the hunk
+	 * 						piece
+	 */
 	Hunk *alloc_hunk_entry(const char *hunk_type, int size, reg_t *addr);
 
-	// Deallocates a hunk entry
-	// Parameters: (reg_t) addr: Offset of the hunk entry to delete
+	/**
+	 * Deallocates a hunk entry
+	 * @param[in] addr	Offset of the hunk entry to delete
+	 */
 	void free_hunk_entry(reg_t addr);
 
 
 	// 9. Dynamic Memory
 
-	// Allocate some dynamic memory
-	// Parameters: (int) size: Number of bytes to allocate
-	//             (const char_ *) description: A descriptive string,
-	//				for debugging purposes
-	// Returns   : (unsigned char*): Raw pointer into the allocated dynamic memory
-	//             (reg_t) *addr: The offset of the freshly allocated X
+	/**
+	 * Allocate some dynamic memory
+	 * @param[in]  size			Number of bytes to allocate
+	 * @param[in]  description	A descriptive string for debugging purposes
+	 * @param[out] addr			The offset of the freshly allocated X
+	 * @return					Raw pointer into the allocated dynamic 
+	 * 							memory
+	 */
 	unsigned char *allocDynmem(int size, const char *description, reg_t *addr);
 
-	// Deallocates a piece of dynamic memory
-	// Parameters: (reg_t) addr: Offset of the dynmem chunk to free
+	/**
+	 * Deallocates a piece of dynamic memory
+	 * @param[in] addr	Offset of the dynmem chunk to free
+	 */
 	int freeDynmem(reg_t addr);
 
-	// Gets the description of a dynmem segment
-	// Parameters: (reg_t) addr: Segment to describe
-	// Returns   : (const char *): Pointer to the descriptive string set in
-	// allocDynmem
+	/**
+	 * Gets the description of a dynmem segment
+	 * @param[in] addr	Segment to describe
+	 * @return			Pointer to the descriptive string set in allocDynmem
+	 */
 	const char *getDescription(reg_t addr);
 
 
@@ -251,10 +309,12 @@ public:
 
 	// Generic Operations on Segments and Addresses
 
-	// Dereferences a raw memory pointer
-	// Parameters: (reg_t) reg: The reference to dereference
-	// Returns   : (byte *) The data block referenced
-	//             (int) size: (optionally) the theoretical maximum size of it
+	/**
+	 * Dereferences a raw memory pointer
+	 * @param[in]  reg	The reference to dereference
+	 * @param[out] size	(optional) The theoretical maximum size
+	 * @return			The data block referenced
+	 */
 	byte *dereference(reg_t reg, int *size);
 
 
@@ -266,17 +326,17 @@ public:
 	int initialiseScript(Script &scr, EngineState *s, int script_nr);
 
 private:
-	IntMapper *id_seg_map; // id - script id; seg - index of heap
+	IntMapper *id_seg_map; ///< id - script id; seg - index of heap
 public: // TODO: make private
 	Common::Array<MemObject *> _heap;
 	int reserved_id;
 	int exports_wide;
 	bool isSci1_1;
 
-	SegmentId Clones_seg_id; // ID of the (a) clones segment
-	SegmentId Lists_seg_id; // ID of the (a) list segment
-	SegmentId Nodes_seg_id; // ID of the (a) node segment
-	SegmentId Hunks_seg_id; // ID of the (a) hunk segment
+	SegmentId Clones_seg_id; ///< ID of the (a) clones segment
+	SegmentId Lists_seg_id; ///< ID of the (a) list segment
+	SegmentId Nodes_seg_id; ///< ID of the (a) node segment
+	SegmentId Hunks_seg_id; ///< ID of the (a) hunk segment
 
 private:
 	MemObject *allocNonscriptSegment(MemObjectType type, SegmentId *segid);
@@ -295,11 +355,12 @@ private:
 	Object *scriptObjInit0(EngineState *s, reg_t obj_pos);
 	Object *scriptObjInit11(EngineState *s, reg_t obj_pos);
 
-	/* Check segment validity
-	** Parameters: (int) seg: The segment to validate
-	** Returns   : (bool)	false if 'seg' is an invalid segment
-	**			true  if 'seg' is a valid segment
-	*/
+	/**
+	 * Check segment validity
+	 * @param[in] seg	The segment to validate
+	 * @return 			false if 'seg' is an invalid segment, true if
+	 * 					'seg' is a valid segment
+	 */
 	bool check(SegmentId seg);
 
 	void dbgPrint(const char* msg, void *i);	// for debug only
diff --git a/engines/sci/engine/vm.cpp b/engines/sci/engine/vm.cpp
index 0b84c0ef3c..cbd0b0cfbb 100644
--- a/engines/sci/engine/vm.cpp
+++ b/engines/sci/engine/vm.cpp
@@ -193,7 +193,7 @@ int script_error(EngineState *s, const char *file, int line, const char *reason)
 }
 #define CORE_ERROR(area, msg) script_error(s, "[" area "] " __FILE__, __LINE__, msg)
 
-reg_t get_class_address(EngineState *s, int classnr, int lock, reg_t caller) {
+reg_t get_class_address(EngineState *s, int classnr, SCRIPT_GET lock, reg_t caller) {
 
 	if (NULL == s) {
 		warning("vm.c: get_class_address(): NULL passed for \"s\"");
@@ -1550,7 +1550,7 @@ SelectorType lookup_selector(EngineState *s, reg_t obj_location, Selector select
 	return _lookup_selector_function(s, obj_location.segment, obj, selector_id, fptr);
 }
 
-SegmentId script_get_segment(EngineState *s, int script_nr, int load) {
+SegmentId script_get_segment(EngineState *s, int script_nr, SCRIPT_GET load) {
 	SegmentId segment;
 
 	if ((load & SCRIPT_GET_LOAD) == SCRIPT_GET_LOAD)
diff --git a/engines/sci/engine/vm.h b/engines/sci/engine/vm.h
index dfbbc39780..379719a448 100644
--- a/engines/sci/engine/vm.h
+++ b/engines/sci/engine/vm.h
@@ -287,8 +287,8 @@ struct Breakpoint {
 };
 
 /**
- * Set this to 1 to abort script execution immediately. Aborting will leave the
- * debug exec stack intact.
+ * Set this to 1 to abort script execution immediately. Aborting will 
+ * leave the debug exec stack intact.
  * Set it to 2 to force a replay afterwards.
  */
 extern int script_abort_flag;
@@ -307,31 +307,36 @@ extern int script_step_counter;
 
 /**
  * Executes function pubfunct of the specified script.
- * Parameters: (EngineState *) s: The state which is to be executed with
- *             (uint16) script: The script which is called
- *             (uint16) pubfunct: The exported script function which is to be called
- *             (StackPtr) sp: Stack pointer position
- *             (reg_t) calling_obj: The heap address of the object which executed the call
- *             (uint16) argc: Number of arguments supplied
- *             (StackPtr) argp: Pointer to the first supplied argument
- * Returns   : (ExecStack *): A pointer to the new exec stack TOS entry
+ * @param[in] s				The state which is to be executed with
+ * @param[in] script		The script which is called
+ * @param[in] pubfunct		The exported script function which is to
+ * 							be called
+ * @param[in] sp			Stack pointer position
+ * @param[in] calling_obj	The heap address of the object that
+ * 							executed the call
+ * @param[in] argc			Number of arguments supplied
+ * @param[in] argp			Pointer to the first supplied argument
+ * @return					A pointer to the new exec stack TOS entry
  */
-ExecStack *execute_method(EngineState *s, uint16 script, uint16 pubfunct, StackPtr sp, reg_t calling_obj,
-	uint16 argc, StackPtr argp);
+ExecStack *execute_method(EngineState *s, uint16 script, uint16 pubfunct, 
+		StackPtr sp, reg_t calling_obj, uint16 argc, StackPtr argp);
 
 
 /**
  * Executes a "send" or related operation to a selector.
- * Parameters: (EngineState *) s: The EngineState to operate on
- *             (reg_t) send_obj: Heap address of the object to send to
- *             (reg_t) work_obj: Heap address of the object initiating the send
- *             (StackPtr) sp: Stack pointer position
- *             (int) framesize: Size of the send as determined by the "send" operation
- *             (StackPtr) argp: Pointer to the beginning of the heap block containing the
- *                              data to be sent. This area is a succession of one or more
- *                              sequences of [selector_number][argument_counter] and then
- *                              "argument_counter" word entries with the parameter values.
- * Returns   : (ExecStack *): A pointer to the new execution stack TOS entry
+ * @param[in] s			The EngineState to operate on
+ * @param[in] send_obj	Heap address of the object to send to
+ * @param[in] work_obj	Heap address of the object initiating the send
+ * @param[in] sp		Stack pointer position
+ * @param[in] framesize	Size of the send as determined by the "send" 
+ * 						operation
+ * @param[in] argp		Pointer to the beginning of the heap block 
+ * 						containing the data to be sent. This area is a 
+ * 						succession of one or more sequences of 
+ * 						[selector_number][argument_counter] and then
+ * 						"argument_counter" word entries with the 
+ * 						parameter values.
+ * @return				A pointer to the new execution stack TOS entry
  */
 ExecStack *send_selector(EngineState *s, reg_t send_obj, reg_t work_obj,
 	StackPtr sp, int framesize, StackPtr argp);
@@ -342,267 +347,300 @@ ExecStack *send_selector(EngineState *s, reg_t send_obj, reg_t work_obj,
 /**
  * Adds an entry to the top of the execution stack.
  *
- * @param s				The state with which to execute
- * @param pc			The initial program counter
- * @param sp			The initial stack pointer
- * @param objp			Pointer to the beginning of the current object
- * @param argc			Number of parameters to call with
- * @param argp			Heap pointer to the first parameter
- * @param selector		The selector by which it was called or
- *						NULL_SELECTOR if n.a. For debugging.
- * @param sendp			Pointer to the object which the message was sent to.
- *						Equal to objp for anything but super.
- * @param origin		Number of the execution stack element this entry was created by
- *						(usually the current TOS number, except for multiple sends).
- * @param local_segment	The segment to use for local variables,
- *						or SCI_XS_CALLEE_LOCALS to use obj's segment.
- * @return a pointer to the new exec stack TOS entry
- */
-ExecStack *add_exec_stack_entry(EngineState *s, reg_t pc, StackPtr sp, reg_t objp, int argc,
-	StackPtr argp, Selector selector, reg_t sendp, int origin, SegmentId local_segment);
+ * @param[in] s				The state with which to execute
+ * @param[in] pc			The initial program counter
+ * @param[in] sp			The initial stack pointer
+ * @param[in] objp			Pointer to the beginning of the current object
+ * @param[in] argc			Number of parameters to call with
+ * @param[in] argp			Heap pointer to the first parameter
+ * @param[in] selector		The selector by which it was called or
+ *							NULL_SELECTOR if n.a. For debugging.
+ * @param[in] sendp			Pointer to the object which the message was 
+ * 							sent to. Equal to objp for anything but super.
+ * @param[in] origin		Number of the execution stack element this
+ * 							entry was created by (usually the current TOS 
+ * 							number, except for multiple sends).
+ * @param[in] local_segment	The segment to use for local variables,
+ *							or SCI_XS_CALLEE_LOCALS to use obj's segment.
+ * @return 					A pointer to the new exec stack TOS entry
+ */
+ExecStack *add_exec_stack_entry(EngineState *s, reg_t pc, StackPtr sp, 
+		reg_t objp, int argc, StackPtr argp, Selector selector, 
+		reg_t sendp, int origin, SegmentId local_segment);
 
 
 /**
  * Adds one varselector access to the execution stack.
- * Parameters: (EngineState *) s: The EngineState to use
- *             (reg_t) objp: Pointer to the object owning the selector
- *             (int) argc: 1 for writing, 0 for reading
- *             (StackPtr) argp: Pointer to the address of the data to write -2
- *             (int) selector: Selector name
- *             (ObjVarRef& ) address: Heap address of the selector
- *             (int) origin: Stack frame which the access originated from
- * Returns   : (ExecStack *): Pointer to the new exec-TOS element
  * This function is called from send_selector only.
+ * @param[in] s			The EngineState to use
+ * @param[in] objp		Pointer to the object owning the selector
+ * @param[in] argc		1 for writing, 0 for reading
+ * @param[in] argp		Pointer to the address of the data to write -2
+ * @param[in] selector	Selector name
+ * @param[in] address	Heap address of the selector
+ * @param[in] origin	Stack frame which the access originated from
+ * @return 				Pointer to the new exec-TOS element
  */
-ExecStack *add_exec_stack_varselector(EngineState *s, reg_t objp, int argc, StackPtr argp,
-	Selector selector, const ObjVarRef& address, int origin);
-
+ExecStack *add_exec_stack_varselector(EngineState *s, reg_t objp, int argc,
+		StackPtr argp, Selector selector, const ObjVarRef& address, 
+		int origin);
 
+/**
+ * This function executes SCI bytecode
+ * It executes the code on s->heap[pc] until it hits a 'ret' operation 
+ * while (stack_base == stack_pos). Requires s to be set up correctly.
+ * @param[in] s			The state to use
+ * @param[in] restoring	1 if s has just been restored, 0 otherwise
+ */
 void run_vm(EngineState *s, int restoring);
-/* Executes the code on s->heap[pc] until it hits a 'ret' operation while (stack_base == stack_pos)
-** Parameters: (EngineState *) s: The state to use
-**             (int) restoring: 1 if s has just been restored, 0 otherwise
-** Returns   : (void)
-** This function will execute SCI bytecode. It requires s to be set up
-** correctly.
-*/
 
+/**
+ * Handles a fatal error condition
+ * @param[in] s		The state to recover from
+ * @param[in] line	Source code line number the error occured in
+ * @param[in] file	File the error occured in
+ */
 void vm_handle_fatal_error(EngineState *s, int line, const char *file);
-/* Handles a fatal error condition
-** Parameters: (EngineState *) s: The state to recover from
-**             (int) line: Source code line number the error occured in
-**             (const char *) file: File the error occured in
-*/
-
-
-void script_debug(EngineState *s, reg_t *pc, StackPtr *sp, StackPtr *pp, reg_t *objp,
-	int *restadjust, SegmentId *segids, reg_t **variables, reg_t **variables_base,
-	int *variables_nr, int bp);
-/* Debugger functionality
-** Parameters: (EngineState *) s: The state at which debugging should take place
-**             (reg_t *) pc: Pointer to the program counter
-**             (StackPtr *) sp: Pointer to the stack pointer
-**             (StackPtr *) pp: Pointer to the frame pointer
-**             (reg_t *) objp: Pointer to the object base pointer
-**             (int *) restadjust: Pointer to the &rest adjustment value
-**	       (SegmentId *) segids: four-element array containing segment IDs for locals etc.
-**	       (reg_t **) variables: four-element array referencing registers for globals etc.
-**	       (reg_t **) variables_base: four-element array referencing
-**                                        register bases for temps etc.
-**	       (int *) variables_nr: four-element array giving sizes for params etc. (may be NULL)
-**             (int) bp: Flag, set to 1 when a breakpoint is triggered
-** Returns   : (void)
-*/
 
+
+/**
+ * Debugger functionality
+ * @param[in] s					The state at which debugging should take
+ * 								place
+ * @param[in] pc				Pointer to the program counter
+ * @param[in] sp				Pointer to the stack pointer
+ * @param[in] pp				Pointer to the frame pointer
+ * @param[in] objp				Pointer to the object base pointer
+ * @param[in] restadjust		Pointer to the &rest adjustment value
+ * @param[in] segids			four-element array containing segment IDs
+ * 								for locals etc.
+ * @param[in] variables			four-element array referencing registers
+ * 								for globals etc.
+ * @param[in] variables_base	four-element array referencing register 
+ * 								bases for temps etc.
+ * @param[in] variables_nr		four-element array giving sizes for params
+ * 								etc. (may be NULL)
+ * @param[in] bp				Flag, set to 1 when a breakpoint is
+ * 								triggered
+ */
+void script_debug(EngineState *s, reg_t *pc, StackPtr *sp, StackPtr *pp, 
+		reg_t *objp, int *restadjust, SegmentId *segids, reg_t **variables,
+		reg_t **variables_base, int *variables_nr, int bp);
+
+/**
+ * Initializes a EngineState block
+ * @param[in] s	The state to initialize
+ * @return		0 on success, 1 if vocab.996 (the class table) is missing
+ * 				or corrupted
+ */
 int script_init_engine(EngineState *s);
-/* Initializes a EngineState block
-** Parameters: (EngineState *) s: The state to initialize
-** Returns   : 0 on success, 1 if vocab.996 (the class table) is missing or corrupted
-*/
 
+/**
+ * Sets the gamestate's save_dir to the parameter path
+ * @param[in] s		The state to set
+ * @param[in] path	Path where save_dir will point to
+ */
 void script_set_gamestate_save_dir(EngineState *s, const char *path);
-/* Sets the gamestate's save_dir to the parameter path
-** Parameters: (EngineState *) s: The state to set
-**             (const char *) path: Path where save_dir will point to
-** Returns   : (void)
-*/
 
+/**
+ * Frees all additional memory associated with a EngineState block
+ * @param[in] s	The EngineState whose elements should be cleared
+ */
 void script_free_engine(EngineState *s);
-/* Frees all additional memory associated with a EngineState block
-** Parameters: (EngineState *) s: The EngineState whose elements should be cleared
-** Returns   : (void)
-*/
 
+/**
+ * Frees all script memory (heap, hunk, and class tables).
+ * This operation is implicit in script_free_engine(), but is required for
+ * restoring the game state.
+ * @param[in] s	The EngineState to free
+ */
 void script_free_vm_memory(EngineState *s);
-/* Frees all script memory (heap, hunk, and class tables).
-** Parameters: (EngineState *) s: The EngineState to free
-** Returns   : (void)
-** This operation is implicit in script_free_engine(), but is required for restoring
-** the game state.
-*/
-
-
-SelectorType lookup_selector(EngineState *s, reg_t obj, Selector selectorid, ObjVarRef *varp, reg_t *fptr);
-/* Looks up a selector and returns its type and value
-** Parameters: (EngineState *) s: The EngineState to use
-**             (reg_t) obj: Address of the object to look the selector up in
-**             (Selector) selectorid: The selector to look up
-** Returns   : (SelectorType) kSelectorNone if the selector was not found in the object or its superclasses.
-**                            kSelectorVariable if the selector represents an object-relative variable
-**                            kSelectorMethod if the selector represents a method
-**             (ObjVarRef *) *varp: A reference to the selector, if
-**                              it is a variable
-**             (reg_t) *fptr: A reference to the function described by that selector, if it is
-**                            a valid function selector.
-** *varindex is written to iff it is non-NULL and the selector indicates a property of the object.
-** *fptr is written to iff it is non-NULL and the selector indicates a member function of that object.
-*/
 
-enum {
+/**
+ * Looks up a selector and returns its type and value
+ * varindex is written to iff it is non-NULL and the selector indicates a property of the object.
+ * @param[in] s				The EngineState to use
+ * @param[in] obj			Address of the object to look the selector up in
+ * @param[in] selectorid	The selector to look up
+ * @param[out] varp			A reference to the selector, if it is a
+ * 							variable.
+ * @param[out] fptr			A reference to the function described by that
+ * 							selector, if it is a valid function selector.
+ * 							fptr is written to iff it is non-NULL and the
+ * 							selector indicates a member function of that
+ * 							object.
+ * @return					kSelectorNone if the selector was not found in 
+ * 							the object or its superclasses.
+ * 							kSelectorVariable if the selector represents an
+ * 							object-relative variable.
+ * 							kSelectorMethod if the selector represents a
+ * 							method
+ */
+SelectorType lookup_selector(EngineState *s, reg_t obj, Selector selectorid,
+		ObjVarRef *varp, reg_t *fptr);
+
+/**
+ * Parameters for script_get_segment()
+ */
+typedef enum {
 	SCRIPT_GET_DONT_LOAD = 0, /**< Fail if not loaded */
 	SCRIPT_GET_LOAD = 1, /**< Load, if neccessary */
 	SCRIPT_GET_LOCK = 3 /**< Load, if neccessary, and lock */
-};
+} SCRIPT_GET;
 
-SegmentId script_get_segment(EngineState *s, int script_id, int load);
-/* Determines the segment occupied by a certain script
-** Parameters: (EngineState *) s: The state to operate on
-**             (int) script_id: The script in question
-**             (int) load: One of SCRIPT_GET_*
-** Returns   : The script's segment, or 0 on failure
-*/
+/**
+ * Determines the segment occupied by a certain script
+ * @param[in] s			The state to operate on
+ * @param[in] script_id	The script in question
+ * @param[in] load		One of SCRIPT_GET_*
+ * @return				The script's segment, or 0 on failure
+ */
+SegmentId script_get_segment(EngineState *s, int script_id, SCRIPT_GET load);
 
+/**
+ * Looks up an entry of the exports table of a script
+ * @param[in]  s			The state to operate on
+ * @param[in]  script_nr	The script to look up in
+ * @param[out] export_index	The index of the export entry to look up
+ * @return					The handle
+ */
 reg_t script_lookup_export(EngineState *s, int script_nr, int export_index);
-/* Looks up an entry of the exports table of a script
-** Parameters: (EngineState *) s: The state to operate on
-**             (int) script_nr: The script to look up in
-** Returns   : (int) export_index: index of the export entry to look up
-*/
 
+/**
+ * Makes sure that a script and its superclasses get loaded to the heap.
+ * If the script already has been loaded, only the number of lockers is 
+ * increased. All scripts containing superclasses of this script are loaded
+ * recursively as well, unless 'recursive' is set to zero. The 
+ * complementary function is "script_uninstantiate()" below.
+ * @param[in] s			The state to operate on
+ * @param[in] script_nr	The script number to load
+ * @return				The script's segment ID or 0 if out of heap
+ */
 int script_instantiate(EngineState *s, int script_nr);
-/* Makes sure that a script and its superclasses get loaded to the heap
-** Parameters: (EngineState *) s: The state to operate on
-**             (int) script_nr: The script number to load
-** Returns   : (int) The script's segment ID or 0 if out of heap
-** If the script already has been loaded, only the number of lockers is increased.
-** All scripts containing superclasses of this script aret loaded recursively as well,
-** unless 'recursive' is set to zero.
-** The complementary function is "script_uninstantiate()" below.
-*/
-
 
+/**
+ * Decreases the numer of lockers of a script and unloads it if that number
+ * reaches zero. 
+ * This function will recursively unload scripts containing its 
+ * superclasses, if those aren't locked by other scripts as well.
+ * @param[in] s			The state to operate on
+ * @param[in] script_nr	The script number that is requestet to be unloaded
+ */
 void script_uninstantiate(EngineState *s, int script_nr);
-/* Decreases the numer of lockers of a script and unloads it if that number reaches zero
-** Parameters: (EngineState *) s: The state to operate on
-**             (int) script_nr: The script number that is requestet to be unloaded
-** Returns   : (void)
-** This function will recursively unload scripts containing its superclasses, if those
-** aren't locked by other scripts as well.
-*/
-
 
+/**
+ * Initializes an SCI game
+ * This function must be run before script_run() is executed. Graphics data
+ * is initialized iff s->gfx_state != NULL.
+ * @param[in] s	The state to operate on
+ * @return		0 on success, 1 if an error occured.
+ */
 int game_init(EngineState *s);
-/* Initializes an SCI game
-** Parameters: (EngineState *) s: The state to operate on
-** Returns   : (int): 0 on success, 1 if an error occured.
-** This function must be run before script_run() is executed.
-** Graphics data is initialized iff s->gfx_state != NULL.
-*/
 
+/**
+ * Initializes the graphics part of an SCI game
+ * This function may only be called if game_init() did not initialize
+ * the graphics data.
+ * @param[in] s	The state to initialize the graphics in
+ * @return		0 on success, 1 if an error occured
+ */
 int game_init_graphics(EngineState *s);
-/* Initializes the graphics part of an SCI game
-** Parameters: (EngineState *) s: The state to initialize the graphics in
-** Returns   : (int) 0 on success, 1 if an error occured
-** This function may only be called if game_init() did not initialize
-** the graphics data.
-*/
 
+/**
+ * Initializes the sound part of an SCI game
+ * This function may only be called if game_init() did not initialize
+ * the sound data.
+ * @param[in] s				The state to initialize the sound in
+ * @param[in] sound_flags	Flags to pass to the sound subsystem
+ * @return					0 on success, 1 if an error occured
+ */
 int game_init_sound(EngineState *s, int sound_flags);
-/* Initializes the sound part of an SCI game
-** Parameters: (EngineState *) s: The state to initialize the sound in
-**             (int) sound_flags:  Flags to pass to the sound subsystem
-** Returns   : (int) 0 on success, 1 if an error occured
-** This function may only be called if game_init() did not initialize
-** the graphics data.
-*/
-
 
+/**
+ * Runs an SCI game
+ * This is the main function for SCI games. It takes a valid state, loads
+ * script 0 to it, finds the game object, allocates a stack, and runs the
+ * init method of the game object. In layman's terms, this runs an SCI game.
+ * Note that, EngineState *s may be changed during the game, e.g. if a game
+ * state is restored.
+ * @param[in] s	Pointer to the pointer of the state to operate on
+ * @return		0 on success, 1 if an error occured.
+ */
 int game_run(EngineState **s);
-/* Runs an SCI game
-** Parameters: (EngineState **) s: Pointer to the pointer of the state to operate on
-** Returns   : (int): 0 on success, 1 if an error occured.
-** This is the main function for SCI games. It takes a valid state, loads script 0 to it,
-** finds the game object, allocates a stack, and runs the init method of the game object.
-** In layman's terms, this runs an SCI game.
-** By the way, *s may be changed during the game, e.g. if a game state is restored.
-*/
 
+/**
+ * Restores an SCI game state and runs the game
+ * This restores a savegame; otherwise, it behaves just like game_run().
+ * @param[in] s				Pointer to the pointer of the state to
+ * 							operate on
+ * @param[in] savegame_name	Name of the savegame to restore
+ * @return					0 on success, 1 if an error occured.
+ */
 int game_restore(EngineState **s, char *savegame_name);
-/* Restores an SCI game state and runs the game
-** Parameters: (EngineState **) s: Pointer to the pointer of the state to operate on
-**             (char *) savegame_name: Name of the savegame to restore
-** Returns   : (int): 0 on success, 1 if an error occured.
-** This restores a savegame; otherwise, it behaves just like game_run().
-*/
 
+/**
+ * Uninitializes an initialized SCI game
+ * This function should be run after each script_run() call.
+ * @param[in] s	The state to operate on
+ * @return		0 on success, 1 if an error occured.
+ */
 int game_exit(EngineState *s);
-/* Uninitializes an initialized SCI game
-** Parameters: (EngineState *) s: The state to operate on
-** Returns   : (int): 0 on success, 1 if an error occured.
-** This function should be run after each script_run() call.
-*/
 
+/**
+ * Instructs the virtual machine to abort
+ */
 void quit_vm();
-/* Instructs the virtual machine to abort
-** Paramteres: (void)
-** Returns   : (void)
-*/
 
+/**
+ * Allocates "kernel" memory and returns a handle suitable to be passed on
+ * to SCI scripts
+ * @param[in] s		Pointer to the EngineState to operate on
+ * @param[in] type	A free-form type description string (static)
+ * @param[in] space	The space to allocate
+ * @return			The handle
+ */
 reg_t kalloc(EngineState *s, const char *type, int space);
-/* Allocates "kernel" memory and returns a handle suitable to be passed on to SCI scripts
-** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
-**             (const char *) type: A free-form type description string (static)
-**             (int) space: The space to allocate
-** Returns   : (reg_t) The handle
-*/
 
+/**
+ * Returns a pointer to "kernel" memory based on the handle
+ * @param[in] s			Pointer to the EngineState to operate on
+ * @param[in] handle	The handle to use
+ * @return				A pointer to the allocated memory
+ */
 byte *kmem(EngineState *s, reg_t handle);
-/* Returns a pointer to "kernel" memory based on the handle
-** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
-**             (reg_t) handle: The handle to use
-** Returns   : (byte *) A pointer to the allocated memory
-*/
-
 
+/**
+ * Frees all "kernel" memory associated with a handle
+ * @param[in] s			Pointer to the EngineState to operate on
+ * @param[in] handle	The handle to free
+ * @return				0 on success, 1 otherwise
+ */
 int kfree(EngineState *s, reg_t handle);
-/* Frees all "kernel" memory associated with a handle
-** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
-**             (reg_t) handle: The handle to free
-** Returns   : (int) 0 on success, 1 otherwise
-*/
 
+/**
+ * Determines the name of an object
+ * @param[in] s		Pointer to the EngineState to operate on
+ * @param[in] pos	Location of the object whose name we want to inspect
+ * @return			A name for that object, or a string describing an error
+ * 					that occured while looking it up. The string is stored
+ * 					in a static buffer and need not be freed (neither may
+ * 					it be modified).
+ */
 const char *obj_get_name(EngineState *s, reg_t pos);
-/* Determines the name of an object
-** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
-**             (reg_t) pos: Location of the object whose name we want to
-**                          inspect
-** Returns   : (const char *) A name for that object, or a string describing
-**                            an error that occured while looking it up
-** The string is stored in a static buffer and need not be freed (neither
-** may it be modified).
-*/
 
+/**
+ * Retrieves an object from the specified location
+ * @param[in] s			Pointer to the EngineState to operate on
+ * @param[in] offset	The object's offset
+ * @return				The object in question, or NULL if there is none
+ */
 Object *obj_get(EngineState *s, reg_t offset);
-/* Retrieves an object from the specified location
-** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
-**             (reg_t) offset: The object's offset
-** Returns   : (Object *) The object in question, or NULL if there is none
-*/
 
+/**
+ * Shrink execution stack to size.
+ * Contains an assert it is not already smaller.
+ */
 void shrink_execution_stack(EngineState *s, uint size);
-/* Shrink execution stack to size.
-** Contains an assert it is not already smaller.
-*/
 
 } // End of namespace Sci