SCI: cleanup

svn-id: r40959

11 files changed, 182 insertions, 184 deletions

diff --git a/engines/sci/decompressor.h b/engines/sci/decompressor.h
index 9f6e7908cc..9fd7510e3b 100644
--- a/engines/sci/decompressor.h
+++ b/engines/sci/decompressor.h
@@ -23,12 +23,13 @@
  *
  */
 
-#ifndef SCI_SCICORE_DECOMPRESSOR_H
-#define SCI_SCICORE_DECOMPRESSOR_H
+#ifndef SCI_DECOMPRESSOR_H
+#define SCI_DECOMPRESSOR_H
 
 #include "common/file.h"
 
 namespace Sci {
+
 enum ResourceCompression {
 	kCompUnknown = -1,
 	kCompNone = 0,
@@ -42,10 +43,11 @@ enum ResourceCompression {
 #endif
 	kCompDCL
 };
-//----------------------------------------------
-// Base class for decompressors
-// Simply copies nPacked bytes from src to dest
-//----------------------------------------------
+
+/**
+ * Base class for decompressors.
+ * Simply copies nPacked bytes from src to dest.
+ */
 class Decompressor {
 public:
 	Decompressor() {}
@@ -116,9 +118,9 @@ protected:
 	byte *_dest;
 };
 
-//----------------------------------------------
-// Huffman decompressor
-//----------------------------------------------
+/**
+ * Huffman decompressor
+ */
 class DecompressorHuffman : public Decompressor {
 public:
 	int unpack(Common::ReadStream *src, byte *dest, uint32 nPacked, uint32 nUnpacked);
@@ -129,10 +131,10 @@ protected:
 	byte *_nodes;
 };
 
-//----------------------------------------------
-// LZW-like decompressor for SCI01/SCI1
-// TODO: Needs clean-up of post-processing fncs
-//----------------------------------------------
+/**
+ * LZW-like decompressor for SCI01/SCI1.
+ * TODO: Needs clean-up of post-processing fncs
+ */
 class DecompressorLZW : public Decompressor {
 public:
 	DecompressorLZW(int nCompression) {
@@ -169,9 +171,9 @@ protected:
 	int _compression;
 };
 
-//----------------------------------------------
-// DCL decompressor for SCI1.1
-//----------------------------------------------
+/**
+ * DCL decompressor for SCI1.1
+ */
 class DecompressorDCL : public Decompressor {
 public:
 	int unpack(Common::ReadStream *src, byte *dest, uint32 nPacked, uint32 nUnpacked);
@@ -182,9 +184,9 @@ protected:
 };
 
 #ifdef ENABLE_SCI32
-//----------------------------------------------
-// STACpack decompressor for SCI32
-//----------------------------------------------
+/**
+ * STACpack decompressor for SCI32
+ */
 class DecompressorLZS : public Decompressor {
 public:
 	int unpack(Common::ReadStream *src, byte *dest, uint32 nPacked, uint32 nUnpacked);
diff --git a/engines/sci/engine/kernel.cpp b/engines/sci/engine/kernel.cpp
index 31d5dc722c..ca759b6315 100644
--- a/engines/sci/engine/kernel.cpp
+++ b/engines/sci/engine/kernel.cpp
@@ -34,6 +34,9 @@
 namespace Sci {
 
 
+/** The string used to identify the "unknown" SCI0 function for each game */
+#define SCRIPT_UNKNOWN_FUNCTION_STRING "[Unknown]"
+
 enum KernelFunctionType {
 	KF_NEW = 1,
 	KF_NONE = -1, /**< No mapping, but name is known */
diff --git a/engines/sci/engine/kmisc.cpp b/engines/sci/engine/kmisc.cpp
index e1772926d7..f575afa573 100644
--- a/engines/sci/engine/kmisc.cpp
+++ b/engines/sci/engine/kmisc.cpp
@@ -248,12 +248,7 @@ reg_t kstub(EngineState *s, int funct_nr, int argc, reg_t *argv) {
 }
 
 reg_t kNOP(EngineState *s, int funct_nr, int argc, reg_t *argv) {
-	warning("Kernel function 0x%02x invoked: unmapped", funct_nr);
-
-	if (s->_kfuncTable[funct_nr].orig_name != SCRIPT_UNKNOWN_FUNCTION_STRING) {
-		warning(" (but its name is known to be %s)", s->_kfuncTable[funct_nr].orig_name.c_str());
-	}
-
+	warning("Kernel function 0x%02x (%s) invoked: unmapped", funct_nr, s->_kfuncTable[funct_nr].orig_name.c_str());
 	return NULL_REG;
 }
 
diff --git a/engines/sci/engine/ksound.cpp b/engines/sci/engine/ksound.cpp
index 684b007042..78b27794a6 100644
--- a/engines/sci/engine/ksound.cpp
+++ b/engines/sci/engine/ksound.cpp
@@ -34,57 +34,63 @@
 
 namespace Sci {
 
-#define _K_SCI0_SOUND_INIT_HANDLE 0
-#define _K_SCI0_SOUND_PLAY_HANDLE 1
-#define _K_SCI0_SOUND_NOP 2
-#define _K_SCI0_SOUND_DISPOSE_HANDLE 3
-#define _K_SCI0_SOUND_MUTE_SOUND 4
-#define _K_SCI0_SOUND_STOP_HANDLE 5
-#define _K_SCI0_SOUND_SUSPEND_HANDLE 6
-#define _K_SCI0_SOUND_RESUME_HANDLE 7
-#define _K_SCI0_SOUND_VOLUME 8
-#define _K_SCI0_SOUND_UPDATE_VOL_PRI 9
-#define _K_SCI0_SOUND_FADE_HANDLE 10
-#define _K_SCI0_SOUND_GET_POLYPHONY 11
-#define _K_SCI0_SOUND_PLAY_NEXT 12
-
-#define _K_SCI01_SOUND_MASTER_VOLME 0 /* Set/Get */
-#define _K_SCI01_SOUND_MUTE_SOUND 1
-#define _K_SCI01_SOUND_UNUSED 2
-#define _K_SCI01_SOUND_GET_POLYPHONY 3
-#define _K_SCI01_SOUND_UPDATE_HANDLE 4
-#define _K_SCI01_SOUND_INIT_HANDLE 5
-#define _K_SCI01_SOUND_DISPOSE_HANDLE 6
-#define _K_SCI01_SOUND_PLAY_HANDLE 7
-#define _K_SCI01_SOUND_STOP_HANDLE 8
-#define _K_SCI01_SOUND_SUSPEND_HANDLE 9 /* or resume */
-#define _K_SCI01_SOUND_FADE_HANDLE 10
-#define _K_SCI01_SOUND_UPDATE_CUES 11
-#define _K_SCI01_SOUND_MIDI_SEND 12
-#define _K_SCI01_SOUND_REVERB 13 /* Get/Set */
-#define _K_SCI01_SOUND_HOLD 14
-
-#define _K_SCI1_SOUND_MASTER_VOLME 0 /* Set/Get */
-#define _K_SCI1_SOUND_MUTE_SOUND 1
-#define _K_SCI1_SOUND_UNUSED1 2
-#define _K_SCI1_SOUND_GET_POLYPHONY 3
-#define _K_SCI1_SOUND_GET_AUDIO_CAPABILITY 4
-#define _K_SCI1_SOUND_SUSPEND_SOUND 5
-#define _K_SCI1_SOUND_INIT_HANDLE 6
-#define _K_SCI1_SOUND_DISPOSE_HANDLE 7
-#define _K_SCI1_SOUND_PLAY_HANDLE 8
-#define _K_SCI1_SOUND_STOP_HANDLE 9
-#define _K_SCI1_SOUND_SUSPEND_HANDLE 10 /* or resume */
-#define _K_SCI1_SOUND_FADE_HANDLE 11
-#define _K_SCI1_SOUND_HOLD_HANDLE 12
-#define _K_SCI1_SOUND_UNUSED2 13
-#define _K_SCI1_SOUND_SET_HANDLE_VOLUME 14
-#define _K_SCI1_SOUND_SET_HANDLE_PRIORITY 15
-#define _K_SCI1_SOUND_SET_HANDLE_LOOP 16
-#define _K_SCI1_SOUND_UPDATE_CUES 17
-#define _K_SCI1_SOUND_MIDI_SEND 18
-#define _K_SCI1_SOUND_REVERB 19 /* Get/Set */
-#define _K_SCI1_SOUND_UPDATE_VOL_PRI 20
+enum {
+	_K_SCI0_SOUND_INIT_HANDLE = 0,
+	_K_SCI0_SOUND_PLAY_HANDLE = 1,
+	_K_SCI0_SOUND_NOP = 2,
+	_K_SCI0_SOUND_DISPOSE_HANDLE = 3,
+	_K_SCI0_SOUND_MUTE_SOUND = 4,
+	_K_SCI0_SOUND_STOP_HANDLE = 5,
+	_K_SCI0_SOUND_SUSPEND_HANDLE = 6,
+	_K_SCI0_SOUND_RESUME_HANDLE = 7,
+	_K_SCI0_SOUND_VOLUME = 8,
+	_K_SCI0_SOUND_UPDATE_VOL_PRI = 9,
+	_K_SCI0_SOUND_FADE_HANDLE = 10,
+	_K_SCI0_SOUND_GET_POLYPHONY = 11,
+	_K_SCI0_SOUND_PLAY_NEXT = 12
+};
+
+enum {
+	_K_SCI01_SOUND_MASTER_VOLME = 0, /* Set/Get */
+	_K_SCI01_SOUND_MUTE_SOUND = 1,
+	_K_SCI01_SOUND_UNUSED = 2,
+	_K_SCI01_SOUND_GET_POLYPHONY = 3,
+	_K_SCI01_SOUND_UPDATE_HANDLE = 4,
+	_K_SCI01_SOUND_INIT_HANDLE = 5,
+	_K_SCI01_SOUND_DISPOSE_HANDLE = 6,
+	_K_SCI01_SOUND_PLAY_HANDLE = 7,
+	_K_SCI01_SOUND_STOP_HANDLE = 8,
+	_K_SCI01_SOUND_SUSPEND_HANDLE = 9, /* or resume */
+	_K_SCI01_SOUND_FADE_HANDLE = 10,
+	_K_SCI01_SOUND_UPDATE_CUES = 11,
+	_K_SCI01_SOUND_MIDI_SEND = 12,
+	_K_SCI01_SOUND_REVERB = 13, /* Get/Set */
+	_K_SCI01_SOUND_HOLD = 14
+};
+
+enum {
+	_K_SCI1_SOUND_MASTER_VOLME = 0, /* Set/Get */
+	_K_SCI1_SOUND_MUTE_SOUND = 1,
+	_K_SCI1_SOUND_UNUSED1 = 2,
+	_K_SCI1_SOUND_GET_POLYPHONY = 3,
+	_K_SCI1_SOUND_GET_AUDIO_CAPABILITY = 4,
+	_K_SCI1_SOUND_SUSPEND_SOUND = 5,
+	_K_SCI1_SOUND_INIT_HANDLE = 6,
+	_K_SCI1_SOUND_DISPOSE_HANDLE = 7,
+	_K_SCI1_SOUND_PLAY_HANDLE = 8,
+	_K_SCI1_SOUND_STOP_HANDLE = 9,
+	_K_SCI1_SOUND_SUSPEND_HANDLE = 10, /* or resume */
+	_K_SCI1_SOUND_FADE_HANDLE = 11,
+	_K_SCI1_SOUND_HOLD_HANDLE = 12,
+	_K_SCI1_SOUND_UNUSED2 = 13,
+	_K_SCI1_SOUND_SET_HANDLE_VOLUME = 14,
+	_K_SCI1_SOUND_SET_HANDLE_PRIORITY = 15,
+	_K_SCI1_SOUND_SET_HANDLE_LOOP = 16,
+	_K_SCI1_SOUND_UPDATE_CUES = 17,
+	_K_SCI1_SOUND_MIDI_SEND = 18,
+	_K_SCI1_SOUND_REVERB = 19, /* Get/Set */
+	_K_SCI1_SOUND_UPDATE_VOL_PRI = 20
+};
 
 enum AudioCommands {
 	// TODO: find the difference between kSci1AudioWPlay and kSci1AudioPlay
@@ -110,7 +116,7 @@ enum AudioSyncCommands {
 
 #define FROBNICATE_HANDLE(reg) ((reg).segment << 16 | (reg).offset)
 #define DEFROBNICATE_HANDLE(handle) (make_reg((handle >> 16) & 0xffff, handle & 0xffff))
-#define SCRIPT_ASSERT_ZERO(fun) if (fun) script_debug_flag = script_error_flag = 1;
+#define SCRIPT_ASSERT_ZERO(fun) do { if (fun) script_debug_flag = script_error_flag = 1; } while(0)
 
 
 static void script_set_priority(EngineState *s, reg_t obj, int priority) {
diff --git a/engines/sci/engine/sciconsole.cpp b/engines/sci/engine/sciconsole.cpp
index 38027ce184..7332a22193 100644
--- a/engines/sci/engine/sciconsole.cpp
+++ b/engines/sci/engine/sciconsole.cpp
@@ -34,8 +34,6 @@
 
 namespace Sci {
 
-#ifdef SCI_CONSOLE
-
 // console commands
 
 static int c_list(EngineState *s, const Common::Array<cmd_param_t> &cmdParams); // lists various types of things
@@ -919,6 +917,4 @@ static int c_hexgrep(EngineState *s, const Common::Array<cmd_param_t> &cmdParams
 	return 0;
 }
 
-#endif // SCI_CONSOLE
-
 } // End of namespace Sci
diff --git a/engines/sci/engine/sciconsole.h b/engines/sci/engine/sciconsole.h
index b2060143aa..96a3d71608 100644
--- a/engines/sci/engine/sciconsole.h
+++ b/engines/sci/engine/sciconsole.h
@@ -38,8 +38,6 @@
 #include "sci/engine/state.h"
 #include "sci/engine/vm_types.h"
 
-#define SCI_CONSOLE
-
 namespace Sci {
 
 struct gfx_pixmap_t;
diff --git a/engines/sci/gfx/picfill.cpp b/engines/sci/gfx/picfill.cpp
index b5ebf9d228..72aaf03f13 100644
--- a/engines/sci/gfx/picfill.cpp
+++ b/engines/sci/gfx/picfill.cpp
@@ -139,7 +139,7 @@ static void AUXBUF_FILL_HELPER(gfxr_pic_t *pic, int old_xl, int old_xr, int y, i
 
 		if ((ytotal + xl) < 0) {
 			fprintf(stderr, "AARGH-%d\n", __LINE__);
-			BREAKPOINT()
+			BREAKPOINT();
 		}
 		if ((ytotal + xr + 1) > 64000) {
 			fprintf(stderr, "AARGH-%d\n", __LINE__);
diff --git a/engines/sci/resource.h b/engines/sci/resource.h
index 60f3ea1d26..ef1c08e5c7 100644
--- a/engines/sci/resource.h
+++ b/engines/sci/resource.h
@@ -45,28 +45,26 @@ namespace Sci {
 /** The maximum allowed size for a compressed or decompressed resource */
 #define SCI_MAX_RESOURCE_SIZE 0x0400000
 
-/*** RESOURCE STATUS TYPES ***/
+/** Resource status types */
 enum ResourceStatus {
 	kResStatusNoMalloc = 0,
 	kResStatusAllocated,
-	kResStatusEnqueued, /* In the LRU queue */
-	kResStatusLocked /* Allocated and in use */
+	kResStatusEnqueued, /**< In the LRU queue */
+	kResStatusLocked /**< Allocated and in use */
 };
 
-/*** INITIALIZATION RESULT TYPES ***/
-#define SCI_ERROR_IO_ERROR 1
-#define SCI_ERROR_INVALID_RESMAP_ENTRY 2
-/* Invalid resource.map entry */
-#define SCI_ERROR_RESMAP_NOT_FOUND 3
-#define SCI_ERROR_NO_RESOURCE_FILES_FOUND 4
-/* No resource at all was found */
-#define SCI_ERROR_UNKNOWN_COMPRESSION 5
-#define SCI_ERROR_DECOMPRESSION_ERROR 6
-/* sanity checks failed during decompression */
-#define SCI_ERROR_RESOURCE_TOO_BIG 8
-/* Resource size exceeds SCI_MAX_RESOURCE_SIZE */
-
-/* the first critical error number */
+/** Initialization result types */
+enum {
+	SCI_ERROR_IO_ERROR = 1,
+	SCI_ERROR_INVALID_RESMAP_ENTRY = 2,	/**< Invalid resource.map entry */
+	SCI_ERROR_RESMAP_NOT_FOUND = 3,
+	SCI_ERROR_NO_RESOURCE_FILES_FOUND = 4,	/**< No resource at all was found */
+	SCI_ERROR_UNKNOWN_COMPRESSION = 5,
+	SCI_ERROR_DECOMPRESSION_ERROR = 6,	/**< sanity checks failed during decompression */
+	SCI_ERROR_RESOURCE_TOO_BIG = 8	/**< Resource size exceeds SCI_MAX_RESOURCE_SIZE */
+
+	/* the first critical error number */
+};
 
 #define SCI_VERSION_1 SCI_VERSION_1_EARLY
 
@@ -92,7 +90,7 @@ enum ResSourceType {
 
 extern const char *sci_error_types[];
 extern const char *sci_version_types[];
-extern const int sci_max_resource_nr[]; /* Highest possible resource numbers */
+extern const int sci_max_resource_nr[]; /**< Highest possible resource numbers */
 
 
 enum ResourceType {
@@ -128,7 +126,7 @@ const char *getResourceTypeSuffix(ResourceType restype);
 /* Used for autodetection */
 
 
-// resource type for SCI1 resource.map file
+/** resource type for SCI1 resource.map file */
 struct resource_index_t {
 	uint16 wOffset;
 	uint16 wSize;
@@ -156,20 +154,20 @@ public:
 	byte *data;
 	uint16 number;
 	ResourceType type;
-	uint32 id;	// contains number and type.
+	uint32 id;	//!< contains number and type.
 	unsigned int size;
-	unsigned int file_offset; /* Offset in file */
+	unsigned int file_offset; /**< Offset in file */
 	ResourceStatus status;
-	unsigned short lockers; /* Number of places where this resource was locked */
+	unsigned short lockers; /**< Number of places where this resource was locked */
 	ResourceSource *source;
 };
 
 
 class ResourceManager {
 public:
-	int _sciVersion; /* SCI resource version to use */
-	int _mapVersion; // RESOURCE.MAP version
-	int _volVersion; // RESOURCE.0xx version
+	int _sciVersion; //!< SCI resource version to use */
+	int _mapVersion; //!< RESOURCE.MAP version
+	int _volVersion; //!< RESOURCE.0xx version
 
 	/**
 	 * Creates a new SCI resource manager.
@@ -184,13 +182,14 @@ public:
 	ResourceManager(int version, int maxMemory);
 	~ResourceManager();
 
-	//! Looks up a resource's data
-	/**	@param type: The resource type to look for
-	 *	@param number: The resource number to search
-	 *	@param lock: non-zero iff the resource should be locked
-	 *	@return (Resource *): The resource, or NULL if it doesn't exist
-	 *	@note Locked resources are guaranteed not to have their contents freed until
-	 *		they are unlocked explicitly (by unlockResource).
+	/**
+	 * Looks up a resource's data.
+	 * @param type: The resource type to look for
+	 * @param number: The resource number to search
+	 * @param lock: non-zero iff the resource should be locked
+	 * @return (Resource *): The resource, or NULL if it doesn't exist
+	 * @note Locked resources are guaranteed not to have their contents freed until
+	 *       they are unlocked explicitly (by unlockResource).
 	 */
 	Resource *findResource(ResourceType type, int number, int lock);
 
@@ -215,37 +214,42 @@ public:
 	Resource *testResource(ResourceType type, int number);
 
 protected:
-	int _maxMemory; // Config option: Maximum total byte number allocated
+	int _maxMemory; //!< Config option: Maximum total byte number allocated
 	ResourceSource *_sources;
-	int _memoryLocked;	// Amount of resource bytes in locked memory
-	int _memoryLRU;		// Amount of resource bytes under LRU control
-	Common::List<Resource *> _LRU; // Last Resource Used list
+	int _memoryLocked;	//!< Amount of resource bytes in locked memory
+	int _memoryLRU;		//!< Amount of resource bytes under LRU control
+	Common::List<Resource *> _LRU; //!< Last Resource Used list
 	Common::HashMap<uint32, Resource *> _resMap;
-	Common::List<Common::File *> _volumeFiles; // list of opened volume files
+	Common::List<Common::File *> _volumeFiles; //!< list of opened volume files
 
-	/* Add a path to the resource manager's list of sources.
-	** Returns: A pointer to the added source structure, or NULL if an error occurred.
-	*/
+	/**
+	 * Add a path to the resource manager's list of sources.
+	 * @return a pointer to the added source structure, or NULL if an error occurred.
+	 */
 	ResourceSource *addPatchDir(const char *path);
 
 	ResourceSource *getVolume(ResourceSource *map, int volume_nr);
 
-	//! Add a volume to the resource manager's list of sources.
-	/** @param map		The map associated with this volume
-	 *	@param filename	The name of the volume to add
-	 *	@param extended_addressing	1 if this volume uses extended addressing,
-	 *                                        0 otherwise.
-	 *	@return A pointer to the added source structure, or NULL if an error occurred.
+	/**
+	 * Add a volume to the resource manager's list of sources.
+	 * @param map		The map associated with this volume
+	 * @param filename	The name of the volume to add
+	 * @param extended_addressing	1 if this volume uses extended addressing,
+	 *                              0 otherwise.
+	 * @return A pointer to the added source structure, or NULL if an error occurred.
 	 */
 	ResourceSource *addVolume(ResourceSource *map, const char *filename,
 	                          int number, int extended_addressing);
-	//! Add an external (i.e. separate file) map resource to the resource manager's list of sources.
-	/**	@param file_name	 The name of the volume to add
-	 *	@return		A pointer to the added source structure, or NULL if an error occurred.
+	/**
+	 * Add an external (i.e., separate file) map resource to the resource manager's list of sources.
+	 * @param file_name	 The name of the volume to add
+	 * @return		A pointer to the added source structure, or NULL if an error occurred.
 	 */
 	ResourceSource *addExternalMap(const char *file_name);
-	//! Scans newly registered resource sources for resources, earliest addition first.
-	/** @param detected_version: Pointer to the detected version number,
+
+	/**
+	 * Scans newly registered resource sources for resources, earliest addition first.
+	 * @param detected_version: Pointer to the detected version number,
 	 *					 used during startup. May be NULL.
 	 * @return One of SCI_ERROR_*.
 	 */
@@ -264,21 +268,23 @@ protected:
 	int detectMapVersion();
 	int detectVolVersion();
 
-	/* Reads the SCI0 resource.map file from a local directory
-	** Returns   : (int) 0 on success, an SCI_ERROR_* code otherwise
-	*/
+	/**
+	 * Reads the SCI0 resource.map file from a local directory.
+	 * @return 0 on success, an SCI_ERROR_* code otherwise
+	 */
 	int readResourceMapSCI0(ResourceSource *map);
 
-	/* Reads the SCI1 resource.map file from a local directory
-	** Returns   : (int) 0 on success, an SCI_ERROR_* code otherwise
-	*/
+	/**
+	 * Reads the SCI1 resource.map file from a local directory.
+	 * @return 0 on success, an SCI_ERROR_* code otherwise
+	 */
 	int readResourceMapSCI1(ResourceSource *map);
 
 	/**--- Patch management functions ---*/
 
-	//! Reads patch files from a local directory
-	/** @paramParameters: ResourceSource *source
-	  */
+	/**
+	 * Reads patch files from a local directory.
+	 */
 	void readResourcePatches(ResourceSource *source);
 	void processPatch(ResourceSource *source, ResourceType restype, int resnumber);
 
@@ -287,6 +293,7 @@ protected:
 	void removeFromLRU(Resource *res);
 };
 
+// Used for speech playback in CD games
 class ResourceSync : public Resource {
 public:
 	ResourceSync() {}
@@ -302,6 +309,7 @@ protected:
 	//bool _syncStarted;	// not used
 };
 
+// Used for speech playback in CD games
 class AudioResource {
 public:
 	AudioResource(ResourceManager *resMgr, int sciVersion);
diff --git a/engines/sci/tools.cpp b/engines/sci/tools.cpp
index 864e182705..3eb27017eb 100644
--- a/engines/sci/tools.cpp
+++ b/engines/sci/tools.cpp
@@ -46,11 +46,9 @@ int sci_ffs(int bits) {
 	return retval;
 }
 
-#ifdef SCI_CONSOLE
-
 bool g_redirect_sciprintf_to_gui = false;
 
-int sciprintf(const char *fmt, ...) {
+void sciprintf(const char *fmt, ...) {
 	va_list argp;
 
 	assert(fmt);
@@ -77,10 +75,6 @@ int sciprintf(const char *fmt, ...) {
 	printf("%s", buf);
 
 	free(buf);
-
-	return 1;
 }
 
-#endif // SCI_CONSOLE
-
 } // End of namespace Sci
diff --git a/engines/sci/tools.h b/engines/sci/tools.h
index e8f954b846..66c6638510 100644
--- a/engines/sci/tools.h
+++ b/engines/sci/tools.h
@@ -31,19 +31,18 @@
 
 namespace Sci {
 
-int sciprintf(const char *fmt, ...) GCC_PRINTF(1, 2);
-/* Prints a string to the console stack
-** Parameters: fmt: a printf-style format string
-**             ...: Additional parameters as defined in fmt
-** Returns   : (int) 1
-** Implementation is in src/console.c
-*/
+/**
+ * Prints a string to the console stack.
+ * @param fmt	a printf-style format string
+ * @param  Additional parameters as defined in fmt
+ */
+void sciprintf(const char *fmt, ...) GCC_PRINTF(1, 2);
 
 /** Find first set bit in bits and return its index. Returns 0 if bits is 0. */
 int sci_ffs(int bits);
 
 
-#  define BREAKPOINT() { error("Breakpoint in %s, line %d\n", __FILE__, __LINE__); }
+#define BREAKPOINT() do { error("Breakpoint in %s, line %d\n", __FILE__, __LINE__); } while(0)
 
 } // End of namespace Sci
 
diff --git a/engines/sci/vocabulary.h b/engines/sci/vocabulary.h
index 3f121fcbfb..4cef247d36 100644
--- a/engines/sci/vocabulary.h
+++ b/engines/sci/vocabulary.h
@@ -39,9 +39,6 @@ class ResourceManager;
 
 /*#define VOCABULARY_DEBUG */
 
-/** The string used to identify the "unknown" SCI0 function for each game */
-#define SCRIPT_UNKNOWN_FUNCTION_STRING "[Unknown]"
-
 /** Number of bytes allocated on the heap to store bad words if parsing fails */
 #define PARSE_HEAP_SIZE 64
 
@@ -215,18 +212,19 @@ void vocab_get_knames(ResourceManager *resmgr, Common::StringList &names);
 bool vocab_get_words(ResourceManager *resmgr, WordMap &words);
 
 
+/**
+ * Loads all suffixes from the suffix vocabulary.
+ * @param resmgr Resource manager the resources are read from
+ * @return true on success, false on failure
+ */
 bool vocab_get_suffixes(ResourceManager *resmgr, SuffixList &suffixes);
-/* Loads all suffixes from the suffix vocabulary.
-** Parameters: (ResourceManager*) resmgr: Resource manager the resources are
-**                               read from
-** Returns   : true on success, false on failure
-*/
 
+/**
+ * Frees all suffixes in the given list.
+ * @param resmgr The resource manager to free from
+ * @param suffixes: The suffixes to free
+ */
 void vocab_free_suffixes(ResourceManager *resmgr, SuffixList &suffixes);
-/* Frees all suffixes in the given list.
-** Parameters: (ResourceManager *) resmgr: The resource manager to free from
-**             (SuffixList) suffixes: The suffixes to free
-*/
 
 /**
  * Retrieves all grammar rules from the resource data.
@@ -236,8 +234,6 @@ void vocab_free_suffixes(ResourceManager *resmgr, SuffixList &suffixes);
  */
 bool vocab_get_branches(ResourceManager *resmgr, Common::Array<parse_tree_branch_t> &branches);
 
-ResultWord vocab_lookup_word(const char *word, int word_len,
-	const WordMap &words, const SuffixList &suffixes);
 /* Looks up a single word in the words and suffixes list
 ** Parameters: (char *) word: Pointer to the word to look up
 **             (int) word_len: Length of the word to look up
@@ -245,10 +241,10 @@ ResultWord vocab_lookup_word(const char *word, int word_len,
 **             (SuffixList) suffixes: List of suffixes
 ** Returns   : (const ResultWordList &) A list containing 1 or 0 words
 */
+ResultWord vocab_lookup_word(const char *word, int word_len,
+	const WordMap &words, const SuffixList &suffixes);
 
 
-bool vocab_tokenize_string(ResultWordList &retval, const char *sentence,
-	const WordMap &words, const SuffixList &suffixes, char **error);
 /* Tokenizes a string and compiles it into word_ts.
 ** Parameters: (char *) sentence: The sentence to examine
 **             (const WordMap &) words: The words to scan for
@@ -260,9 +256,10 @@ bool vocab_tokenize_string(ResultWordList &retval, const char *sentence,
 ** if not, *error points to a malloc'd copy of the offending word.
 ** The returned list may contain anywords.
 */
+bool vocab_tokenize_string(ResultWordList &retval, const char *sentence,
+	const WordMap &words, const SuffixList &suffixes, char **error);
 
 
-parse_rule_list_t *vocab_build_gnf(const Common::Array<parse_tree_branch_t> &branches);
 /* Constructs the Greibach Normal Form of the grammar supplied in 'branches'
 ** Parameters: (parse_tree_branch_t *) branches: The parser's branches
 ** Returns   : (parse_rule_list_t *): Pointer to a list of singly linked
@@ -272,16 +269,15 @@ parse_rule_list_t *vocab_build_gnf(const Common::Array<parse_tree_branch_t> &bra
 ** branch[0] is used only for a few magical incantations, as it is treated
 ** specially by the SCI parser.
 */
+parse_rule_list_t *vocab_build_gnf(const Common::Array<parse_tree_branch_t> &branches);
 
 
-void vocab_free_rule_list(parse_rule_list_t *rule_list);
 /* Frees a parser rule list as returned by vocab_build_gnf()
 ** Parameters: (parse_rule_list_t *) rule_list: The rule list to free
 */
+void vocab_free_rule_list(parse_rule_list_t *rule_list);
 
 
-int vocab_build_parse_tree(parse_tree_node_t *nodes, const ResultWordList &words,
-	const parse_tree_branch_t &branch0, parse_rule_list_t *rules);
 /* Builds a parse tree from a list of words
 ** Parameters: (parse_tree_node_t *) nodes: A node list to store the tree in (must have
 **                                          at least VOCAB_TREE_NODES entries)
@@ -293,23 +289,24 @@ int vocab_build_parse_tree(parse_tree_node_t *nodes, const ResultWordList &words
 **             or if the sentence structure in 'words' is not part of the language
 **             described by the grammar passed in 'rules'.
 */
+int vocab_build_parse_tree(parse_tree_node_t *nodes, const ResultWordList &words,
+	const parse_tree_branch_t &branch0, parse_rule_list_t *rules);
 
-void vocab_dump_parse_tree(const char *tree_name, parse_tree_node_t *nodes);
 /* Prints a parse tree
 ** Parameters: (const char *) tree_name: Name of the tree to dump (free-form)
 **             (parse_tree_node_t *) nodes: The nodes containing the parse tree
 */
+void vocab_dump_parse_tree(const char *tree_name, parse_tree_node_t *nodes);
 
 
 
-
-int said(EngineState *s, byte *spec, int verbose);
 /* Builds a parse tree from a spec and compares it to a parse tree
 ** Parameters: (EngineState *) s: The affected state
 **             (byte *) spec: Pointer to the spec to build
 **             (int) verbose: Whether to display the parse tree after building it
 ** Returns   : (int) 1 on a match, 0 otherwise
 */
+int said(EngineState *s, byte *spec, int verbose);
 
 /**
  * Gets any word from the specified group. For debugging only.
@@ -319,19 +316,19 @@ int said(EngineState *s, byte *spec, int verbose);
 const char *vocab_get_any_group_word(int group, const WordMap &words);
 
 
-void vocab_decypher_said_block(EngineState *s, byte *pos);
 /* Decyphers a said block and dumps its content via sciprintf.
 ** Parameters: (EngineState *) s: The state to use
 **             (byte *) pos: Pointer to the data to dump
 ** For debugging only.
 */
+void vocab_decypher_said_block(EngineState *s, byte *pos);
 
 
-void vocab_synonymize_tokens(ResultWordList &words, const SynonymList &synonyms);
 /* Synonymizes a token list
 ** Parameters: (ResultWordList &) words: The word list to synonymize
 **             (const SynonymList &) synonyms: Synonym list
 */
+void vocab_synonymize_tokens(ResultWordList &words, const SynonymList &synonyms);
 
 int vocab_gnf_parse(parse_tree_node_t *nodes, const ResultWordList &words,
 	const parse_tree_branch_t &branch0, parse_rule_list_t *tlist, int verbose);