1 files changed, 61 insertions, 17 deletions

diff --git a/common/advancedDetector.h b/common/advancedDetector.h
index 4ce9af8abf..592b019c9b 100644
--- a/common/advancedDetector.h
+++ b/common/advancedDetector.h
@@ -37,6 +37,9 @@ struct ADGameFileDescription {
 	int32 fileSize;  // Optional. Set to -1 to ignore.
 };
 
+#define AD_ENTRY1(f, x) {{ f, 0, x, -1}, {NULL, 0, NULL, 0}}
+#define AD_ENTRY1s(f, x, s) {{ f, 0, x, s}, {NULL, 0, NULL, 0}}
+
 enum ADGameFlags {
 	ADGF_NO_FLAGS = 0,
 	ADGF_DEMO = (1 << 30)
@@ -57,9 +60,14 @@ struct ADGameDescription {
 	uint32 flags;
 };
 
+/**
+ * End marker for a table of ADGameDescription structs. Use this to
+ * terminate a list to be passed to the AdvancedDetector API.
+ */
 #define AD_TABLE_END_MARKER	\
 	{ NULL, NULL, { { NULL, 0, NULL, 0 } }, Common::UNK_LANG, Common::kPlatformUnknown, Common::ADGF_NO_FLAGS }
 
+
 struct ADObsoleteGameID {
 	const char *from;
 	const char *to;
@@ -75,30 +83,66 @@ enum ADFlags {
 	kADFlagFilebasedFallback = (1 << 1)  // Use file based fallback detection
 };
 
+/**
+ * A structure containing all parameters for the AdvancedDetector.
+ * Typically, an engine will have a single instance of this which is
+ * then passed to the various AdvancedDetector functions.
+ */
 struct ADParams {
-	// Pointer to ADGameDescription or its superset structure
+	/**
+	 * Pointer to an array of objects which are either ADGameDescription
+	 * or superset structures (i.e. start with an ADGameDescription member.
+	 * The list is terminated by an entry with a gameid equal to 0
+	 * (see AD_TABLE_END_MARKER).
+	 */
 	const byte *descs;
-	// Size of that superset structure
-	int descItemSize;
-	// Number of bytes to compute MD5 sum for
-	int md5Bytes;
-	// List of all engine targets
+
+	/**
+	 * The size of a single entry of the above descs array. Always
+	 * must be >= sizeof(ADGameDescription).
+	 */
+	uint descItemSize;
+
+	/**
+	 * The number of bytes to compute MD5 sum for. The AdvancedDetector
+	 * is primarily based on computing and matching MD5 checksums of files.
+	 * Since doing that for large files can be slow, it can be restricted
+	 * to a subset of all files.
+	 * Typically this will be set to something between 5 and 50 kilobyte,
+	 * but arbitrary non-zero values are possible.
+	 */
+	uint md5Bytes;
+
+	/**
+	 * A list of all gameids (and their corresponding descriptions) supported
+	 * by this engine.
+	 */
 	const PlainGameDescriptor *list;
-	// Structure for autoupgrading obsolete targets (optional)
+
+	/**
+	 * Structure for autoupgrading obsolete targets (optional)
+	 *
+	 * @todo Properly explain this.
+	 */
 	const Common::ADObsoleteGameID *obsoleteList;
-	// Name of single gameid (optional)
+
+	/**
+	 * Name of single gameid (optional).
+	 *
+	 * @todo Properly explain this -- what does it do?
+	 */
 	const char *singleid;
-	// List of files for file-based fallback detection (optional)
-	const char **fileBased;
-	// Flags
-	uint32 flags;
-};
 
-typedef Array<int> ADList;
-typedef Array<const ADGameDescription*> ADGameDescList;
+	/**
+	 * List of files for file-based fallback detection (optional)
+	 
+	 * @todo Properly explain this
+	 */
+	const char **fileBasedFallback;
 
-#define AD_ENTRY1(f, x) {{ f, 0, x, -1}, {NULL, 0, NULL, 0}}
-#define AD_ENTRY1s(f, x, s) {{ f, 0, x, s}, {NULL, 0, NULL, 0}}
+	/** Flags */
+	uint32 flags;
+};
 
 
 namespace AdvancedDetector {