Some more AdvancedDetector cleanup: Removed kADFlagFilebasedFallback flag (just check whether a fileBasedFallback has been provided); moved some internal definitions, added some doxygen coments, etc.

svn-id: r25570

3 files changed, 68 insertions, 26 deletions

diff --git a/common/advancedDetector.cpp b/common/advancedDetector.cpp
index f243d1f044..d6ec293620 100644
--- a/common/advancedDetector.cpp
+++ b/common/advancedDetector.cpp
@@ -33,6 +33,9 @@
 
 namespace Common {
 
+typedef Array<int> ADList;
+typedef Array<const ADGameDescription*> ADGameDescList;
+
 namespace AdvancedDetector {
 
 /**
@@ -430,13 +433,8 @@ static ADList detectGame(const FSList *fslist, const Common::ADParams &params, L
 			printf("%s: \"%s\", %d\n", file->_key.c_str(), file->_value.c_str(), filesSize[file->_key]);
 	}
 
-	if (params.flags & kADFlagFilebasedFallback) {
-		if (params.fileBased == NULL) {
-			error("Engine %s has FilebasedFallback flag set but list fileBased is empty",
-				  params.singleid); // We may get 0 as singleid here, but let's ignore it
-		}
-
-		const char **ptr = params.fileBased;
+	if (params.fileBasedFallback != 0) {
+		const char **ptr = params.fileBasedFallback;
 
 		// First we create list of files required for detection
 		if (allFiles.empty()) {
@@ -469,7 +467,7 @@ static ADList detectGame(const FSList *fslist, const Common::ADParams &params, L
 		const char **matchEntry = 0;
 		const char **entryStart;
 
-		ptr = params.fileBased;
+		ptr = params.fileBasedFallback;
 
 		while (*ptr) {
 			entryStart = ptr;
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 {
diff --git a/engines/gob/detection.cpp b/engines/gob/detection.cpp
index 98a5372cbb..7140892787 100644
--- a/engines/gob/detection.cpp
+++ b/engines/gob/detection.cpp
@@ -914,7 +914,7 @@ static const ADParams detectionParams = {
 	// List of files for file-based fallback detection (optional)
 	Gob::fileBased,
 	// Flags
-	kADFlagAugmentPreferredTarget | kADFlagFilebasedFallback
+	kADFlagAugmentPreferredTarget
 };
 
 ADVANCED_DETECTOR_DEFINE_PLUGIN(GOB, Gob::GobEngine, detectionParams);