SCI: Cleanup the grammar/vocab code: Move defs from vocabulary.h to grammar.cpp where possible, turn comments into doxygen format etc.

svn-id: r45253

1 files changed, 71 insertions, 79 deletions

diff --git a/engines/sci/vocabulary.h b/engines/sci/vocabulary.h
index cc1a991c4c..00b8780d1c 100644
--- a/engines/sci/vocabulary.h
+++ b/engines/sci/vocabulary.h
@@ -75,14 +75,14 @@ enum {
 	kParseNumber = 4
 };
 
-#define VOCAB_CLASS_ANYWORD 0xff
 /* Anywords are ignored by the parser */
+#define VOCAB_CLASS_ANYWORD 0xff
 
-#define VOCAB_MAGIC_NUMBER_GROUP 0xffd /* 0xffe ? */
 /* This word class is used for numbers */
+#define VOCAB_MAGIC_NUMBER_GROUP 0xffd /* 0xffe ? */
 
-#define VOCAB_TREE_NODES 500
 /* Number of nodes for each parse_tree_node structure */
+#define VOCAB_TREE_NODES 500
 
 #define VOCAB_TREE_NODE_LAST_WORD_STORAGE 0x140
 #define VOCAB_TREE_NODE_COMPARE_TYPE 0x146
@@ -111,8 +111,8 @@ enum {
 #define SAID_LONG(x) ((x) << 8)
 
 struct ResultWord {
-	int _class; /* Word class */
-	int _group; /* Word group */
+	int _class; /**< Word class */
+	int _group; /**< Word group */
 };
 
 typedef Common::List<ResultWord> ResultWordList;
@@ -120,32 +120,18 @@ typedef Common::List<ResultWord> ResultWordList;
 typedef Common::HashMap<Common::String, ResultWord, Common::IgnoreCase_Hash, Common::IgnoreCase_EqualTo> WordMap;
 
 
-struct parse_rule_t {
-	int id; /* non-terminal ID */
-	int first_special; /* first terminal or non-terminal */
-	int specials_nr; /* number of terminals and non-terminals */
-	int length;
-	int data[1]; /* actual data (size 1 to avoid compiler warnings) */
-};
-
-
-struct parse_rule_list_t {
-	int terminal; /* Terminal character this rule matches against or 0 for a non-terminal rule */
-	parse_rule_t *rule;
-	parse_rule_list_t *next;
-};
-
+struct ParseRuleList;
 
 struct suffix_t {
 
-	int class_mask; /* the word class this suffix applies to */
-	int result_class; /* the word class a word is morphed to if it doesn't fail this check */
+	int class_mask; /**< the word class this suffix applies to */
+	int result_class; /**< the word class a word is morphed to if it doesn't fail this check */
 
-	int alt_suffix_length; /* String length of the suffix */
-	int word_suffix_length; /* String length of the other suffix */
+	int alt_suffix_length; /**< String length of the suffix */
+	int word_suffix_length; /**< String length of the other suffix */
 
-	const char *alt_suffix; /* The alternative suffix */
-	const char *word_suffix; /* The suffix as used in the word vocabulary */
+	const char *alt_suffix; /**< The alternative suffix */
+	const char *word_suffix; /**< The suffix as used in the word vocabulary */
 
 };
 
@@ -153,8 +139,8 @@ typedef Common::List<suffix_t> SuffixList;
 
 
 struct synonym_t {
-	int replaceant; /* The word group to replace */
-	int replacement; /* The replacement word group for this one */
+	int replaceant; /**< The word group to replace */
+	int replacement; /**< The replacement word group for this one */
 };
 
 typedef Common::List<synonym_t> SynonymList;
@@ -170,10 +156,10 @@ enum ParseTypes {
 };
 
 struct parse_tree_node_t {
-	short type;  /* leaf or branch */
+	ParseTypes type;  /**< leaf or branch */
 	union {
-		int value;  /* For leaves */
-		short branches[2]; /* For branches */
+		int value;  /**< For leaves */
+		short branches[2]; /**< For branches */
 	} content;
 };
 
@@ -203,38 +189,42 @@ public:
 	ResultWord lookupWord(const char *word, int word_len);
 
 
-	/* Tokenizes a string and compiles it into word_ts.
-	** Parameters: (char *) sentence: The sentence to examine
-	**             (char **) error: Points to a malloc'd copy of the offending text or to NULL on error
-	**             (ResultWordList) retval: A list of word_ts containing the result, or NULL.
-	** Returns   : true on success, false on failure
-	** On error, NULL is returned. If *error is NULL, the sentence did not contain any useful words;
-	** if not, *error points to a malloc'd copy of the offending word.
-	** The returned list may contain anywords.
-	*/
+	/**
+	 * Tokenizes a string and compiles it into word_ts.
+	 * @param[in] retval		A list of words which will be set to the result
+	 * @param[out] sentence		The sentence to examine
+	 * @param[out] error		Points to a malloc'd copy of the offending text or to NULL on error
+	 * @return true on success, false on failure
+	 *
+	 * On error, false is returned. If *error is NULL, the sentence did not
+	 * contain any useful words; if not, *error points to a malloc'd copy of
+	 * the offending word. The returned list may contain anywords.
+	 */
 	bool tokenizeString(ResultWordList &retval, const char *sentence, char **error);
 
-	/* Builds a parse tree from a list of words, using a set of Greibach Normal Form rules
-	** Parameters: 
-	**             (const ResultWordList &) words: The words to build the tree from
-	**             bool verbose: Set to true for debugging
-	** Returns   : 0 on success, 1 if the tree couldn't be built in VOCAB_TREE_NODES nodes
-	**             or if the sentence structure in 'words' is not part of the language
-	**             described by the grammar passed in 'rules'.
-	*/
+	/**
+	 * Builds a parse tree from a list of words, using a set of Greibach Normal
+	 * Form rules.
+	 * @param words		The words to build the tree from
+	 * @param verbose	Set to true for debugging
+	 * @return	0 on success, 1 if the tree couldn't be built in VOCAB_TREE_NODES
+	 *			nodes or if the sentence structure in 'words' is not part of the
+	 *			language described by the grammar passed in 'rules'.
+	 */
 	int parseGNF(const ResultWordList &words, bool verbose = false);
 
-	/* Constructs the Greibach Normal Form of the grammar supplied in 'branches'
-	**             bool verbose: Set to true for debugging.
-	**             If true, the list is freed before the function ends
-	** Returns   : (parse_rule_list_t *): Pointer to a list of singly linked
-	**                                    GNF rules describing the same language
-	**                                    that was described by 'branches'
-	** The original SCI rules are in almost-CNF (Chomsky Normal Form). Note that
-	** branch[0] is used only for a few magical incantations, as it is treated
-	** specially by the SCI parser.
-	*/
-	parse_rule_list_t *buildGNF(bool verbose = false);
+	/**
+	 * Constructs the Greibach Normal Form of the grammar supplied in 'branches'.
+	 * @param verbose	Set to true for debugging. If true, the list is
+	 *					freed before the function ends
+	 * @return	Pointer to a list of singly linked GNF rules describing the same
+	 *			language that was described by 'branches'
+	 *
+	 * The original SCI rules are in almost-CNF (Chomsky Normal Form). Note that
+	 * branch[0] is used only for a few magical incantations, as it is treated
+	 * specially by the SCI parser.
+	 */
+	ParseRuleList *buildGNF(bool verbose = false);
 
 	/**
 	 * Deciphers a said block and dumps its content via printf.
@@ -278,9 +268,6 @@ public:
 
 	int parseNodes(int *i, int *pos, int type, int nr, int argc, const char **argv);
 
-	// Accessed by said()
-	parse_tree_node_t _parserNodes[VOCAB_TREE_NODES]; /**< The parse tree */
-
 private:
 	/**
 	 * Loads all words from the main vocabulary.
@@ -307,40 +294,45 @@ private:
 	 */
 	bool loadBranches();
 
-	/* Frees a parser rule list as returned by vocab_build_gnf()
-	** Parameters: (parse_rule_list_t *) rule_list: The rule list to free
-	*/
-	void freeRuleList(parse_rule_list_t *rule_list);
+	/**
+	 * Frees a parser rule list as returned by vocab_build_gnf().
+	 * @param rule_list		the rule list to free
+	 */
+	void freeRuleList(ParseRuleList *rule_list);
 
 	ResourceManager *_resMan;
 	VocabularyVersions _vocabVersion;
 
 	// Parser-related lists
 	SuffixList _parserSuffixes;
-	parse_rule_list_t *_parserRules; /**< GNF rules used in the parser algorithm */
+	ParseRuleList *_parserRules; /**< GNF rules used in the parser algorithm */
 	Common::Array<parse_tree_branch_t> _parserBranches;
 	WordMap _parserWords;
 	SynonymList _synonyms; /**< The list of synonyms */
+
+public:
+	// Accessed by said()
+	parse_tree_node_t _parserNodes[VOCAB_TREE_NODES]; /**< The parse tree */
 };
 
-/* 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
-*/
+/**
+ * Prints a parse tree.
+ * @param tree_name		Name of the tree to dump (free-form)
+ * @param nodes			The nodes containing the parse tree
+ */
 void vocab_dump_parse_tree(const char *tree_name, parse_tree_node_t *nodes);
 
 
 
-/* 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
-**             (bool) verbose: Whether to display the parse tree after building it
-** Returns   : (int) 1 on a match, 0 otherwise
-*/
+/**
+ * Builds a parse tree from a spec and compares it to a parse tree.
+ * @param s			The affected state
+ * @param spec		Pointer to the spec to build
+ * @param verbose	Whether to display the parse tree after building it
+ * @return 1 on a match, 0 otherwise
+ */
 int said(EngineState *s, byte *spec, bool verbose);
 
-int getAllocatedRulesCount();
-
 } // End of namespace Sci
 
 #endif // SCI_SCICORE_VOCABULARY_H