MUTATIONOFJB: Improve documentation and naming.

10 files changed, 99 insertions, 23 deletions

diff --git a/engines/mutationofjb/commands/camefromcommand.cpp b/engines/mutationofjb/commands/camefromcommand.cpp
index 485e0c54c9..67033b8a53 100644
--- a/engines/mutationofjb/commands/camefromcommand.cpp
+++ b/engines/mutationofjb/commands/camefromcommand.cpp
@@ -26,7 +26,7 @@
 #include "common/str.h"
 
 /** @file
- * "CAMEFROM" <sceneId>
+ * "CAMEFROM " <sceneId>
  *
  * This command tests whether last scene (the scene player came from) is sceneId.
  * If true, the execution continues after this command.
diff --git a/engines/mutationofjb/commands/changecommand.cpp b/engines/mutationofjb/commands/changecommand.cpp
index 5d6833b82c..7d2e7e6910 100644
--- a/engines/mutationofjb/commands/changecommand.cpp
+++ b/engines/mutationofjb/commands/changecommand.cpp
@@ -25,8 +25,6 @@
 #include "mutationofjb/gamedata.h"
 #include "common/translation.h"
 
-namespace MutationOfJB {
-
 /** @file
  * "CHANGE" <entity> " " <register> " " <sceneId> " " <entityId> " " <value>
  *
@@ -43,6 +41,8 @@ namespace MutationOfJB {
  * <value>    *B  Value (variable length).
  */
 
+namespace MutationOfJB {
+
 bool ChangeCommandParser::parseValueString(const Common::String &valueString, bool changeEntity, uint8 &sceneId, uint8 &entityId, ChangeCommand::ChangeRegister &reg, ChangeCommand::ChangeOperation &op, ChangeCommandValue &ccv) {
 	if (changeEntity) {
 		if (valueString.size() < 8) {
diff --git a/engines/mutationofjb/commands/command.h b/engines/mutationofjb/commands/command.h
index 0133d52dd0..b407aa1119 100644
--- a/engines/mutationofjb/commands/command.h
+++ b/engines/mutationofjb/commands/command.h
@@ -33,18 +33,56 @@ class Command;
 class ScriptExecutionContext;
 class ScriptParseContext;
 
+/**
+ * Base class for command parsers.
+ *
+ * The parser's main job is to create a Command instance from input line.
+ */
 class CommandParser {
 public:
 	virtual ~CommandParser();
+
+	/**
+	 * Parses the specified line and possibly returns a Command instance.
+	 *
+	 * @param line Line to parse.
+	 * @param parseCtx Parse context.
+	 * @param command Output parameter for newly created command.
+	 * @return True if the line has been successfully parsed by this parser, false otherwise.
+	 * @note You may return true and set command to nullptr.
+	 * That means the line has been successfully parsed, but no command is needed.
+	 */
 	virtual bool parse(const Common::String &line, ScriptParseContext &parseCtx, Command *&command) = 0;
 
-	/* Old command - created by this parser. */
+	/**
+	 * Called when transitioning parsing between two commands.
+	 *
+	 * For example, cmdParserA->transition(parseCtx, cmdA, cmdB, cmdParserB) is called after command B is done parsing
+	 * to notify command A parser about the transition from command A to command B.
+	 * This is useful for sequential commands, because at the time command A is being parsed,
+	 * we don't have any information about command B, so we cannot set the next pointer.
+	 * Transition method can be used to set the next pointer after command B is available.
+	 *
+	 * @param parseCtx Parse context.
+	 * @param oldCommand Old command (created by this parser).
+	 * @param newCommand New command (created by newCommandParser).
+	 * @param newCommandParser Command parser which created the new command.
+	 */
 	virtual void transition(ScriptParseContext &parseCtx, Command *oldCommand, Command *newCommand, CommandParser *newCommandParser);
 
-	/* Called after parsing. */
+	/**
+	 * Called after the whole script is parsed.
+	 *
+	 * Can be used for cleanup.
+	 *
+	 * @param parseCtx Parse context.
+	 */
 	virtual void finish(ScriptParseContext &parseCtx);
 };
 
+/**
+ * Base class for script commands.
+ */
 class Command {
 public:
 	enum ExecuteResult {
@@ -60,6 +98,7 @@ public:
 
 	virtual Common::String debugString() const = 0;
 };
+
 }
 
 #endif
diff --git a/engines/mutationofjb/commands/definestructcommand.cpp b/engines/mutationofjb/commands/definestructcommand.cpp
index 4ccf2e8631..bea3497a3d 100644
--- a/engines/mutationofjb/commands/definestructcommand.cpp
+++ b/engines/mutationofjb/commands/definestructcommand.cpp
@@ -25,6 +25,22 @@
 #include "mutationofjb/game.h"
 #include "common/debug.h"
 
+/** @file
+ * "DEFINE_STRUCT " <numItemGroups> " " <context> " " <objectId> " " <colorString> <CRLF>
+ * <itemGroup> { <CRLF> <itemGroup> }
+ *
+ * item ::= <questionIndex> " " <responseIndex> " " <nextGroup>
+ * itemGroup ::= <item> " " <item> " " <item> " " <item> " " <item>
+ *
+ * Defines the flow of an interactive conversation.
+ *
+ * Every item group consists of 5 conversation items.
+ * "questionIndex" and "responseIndex" specify what the player and the responder say when the conversation item is selected.
+ * They refer to the line numbers of TOSAY.GER and RESPONSE.GER, respectively.
+ * "nextGroup" refers to the group that follows when the conversation item is selected. A value of 0 indicates end of
+ * conversation.
+ */
+
 namespace MutationOfJB {
 
 bool DefineStructCommandParser::parse(const Common::String &line, ScriptParseContext &parseCtx, Command *&command) {
@@ -52,19 +68,19 @@ bool DefineStructCommandParser::parse(const Common::String &line, ScriptParseCon
 
 		const char *linePtr = convLineStr.c_str();
 
-		ConversationInfo::Line convLine;
+		ConversationInfo::ItemGroup convGroup;
 
 		for (int j = 0; j < 5; ++j) {
 			ConversationInfo::Item convItem;
-			convItem._choice = atoi(linePtr);
+			convItem._question = atoi(linePtr);
 			linePtr += 6;
 			convItem._response = atoi(linePtr);
 			linePtr += 6;
-			convItem._nextLineIndex = atoi(linePtr);
+			convItem._nextGroupIndex = atoi(linePtr);
 			linePtr += 3;
-			convLine._items.push_back(convItem);
+			convGroup.push_back(convItem);
 		}
-		convInfo._lines.push_back(convLine);
+		convInfo._itemGroups.push_back(convGroup);
 	}
 
 	command = new DefineStructCommand(convInfo);
diff --git a/engines/mutationofjb/commands/endblockcommand.cpp b/engines/mutationofjb/commands/endblockcommand.cpp
index c7fbd41f00..8ad11f8946 100644
--- a/engines/mutationofjb/commands/endblockcommand.cpp
+++ b/engines/mutationofjb/commands/endblockcommand.cpp
@@ -28,16 +28,19 @@
 #include "common/translation.h"
 
 /** @file
- * ("#L " | "-L ") <object>
- * ("#W " | "-W ") <object>
- * ("#T " | "-T ") <object>
- * ("#P " | "-P ") <object1>
- * ("#U " | "-U ") <object1> [<object2>]
- * ("#ELSE" | "-ELSE") [<tag>]
- * "#MACRO " <name>
- * "#EXTRA" <name>
+ * <look> | <walk> | <talk> | <pickup> | <use> | <else> | <macro> | <extra> | <endRandom>
  *
- * If a line starts with '#', '=', '-', it is treated as the end of a section.
+ * look ::= ("#L " | "-L ") <object>
+ * walk ::= ("#W " | "-W ") <object>
+ * talk ::= ("#T " | "-T ") <object>
+ * pickup ::= ("#P " | "-P ") <object1>
+ * use ::= ("#U " | "-U ") <object1> [<object2>]
+ * else ::= ("#ELSE" | "-ELSE") [<tag>]
+ * macro ::= "#MACRO " <name>
+ * extra ::= "#EXTRA" <name>
+ * endRandom ::= "\"
+ *
+ * If a line starts with '#', '=', '-', '\' it is treated as the end of a section.
  * However, at the same time it can also start a new section depending on what follows.
  *
  * #L (look), #W (walk), #T (talk), #U (use) sections are executed
@@ -49,6 +52,8 @@
  * #MACRO starts a new macro. Global script can call macros from local script and vice versa.
  *
  * #EXTRA defines an "extra" section. This is called from dialog responses ("TALK TO HIM" command).
+ *
+ * TODO: TIMERPROC.
  */
 
 namespace MutationOfJB {
diff --git a/engines/mutationofjb/commands/ifitemcommand.cpp b/engines/mutationofjb/commands/ifitemcommand.cpp
index d70add9207..eec4621292 100644
--- a/engines/mutationofjb/commands/ifitemcommand.cpp
+++ b/engines/mutationofjb/commands/ifitemcommand.cpp
@@ -28,7 +28,7 @@
 #include "common/translation.h"
 
 /** @file
- * "IFITEM" <item> ["!"]
+ * "IFITEM " <item> [ "!" ]
  *
  * IFITEM command tests whether an item is in the inventory.
  * If it is, execution continues to the next line.
diff --git a/engines/mutationofjb/commands/removeitemcommand.cpp b/engines/mutationofjb/commands/removeitemcommand.cpp
index 21d1123dc2..be8ea2359f 100644
--- a/engines/mutationofjb/commands/removeitemcommand.cpp
+++ b/engines/mutationofjb/commands/removeitemcommand.cpp
@@ -25,7 +25,7 @@
 #include "mutationofjb/gamedata.h"
 
 /** @file
- * "DELITEM" " " <item>
+ * "DELITEM " <item>
  *
  * Removes item from inventory.
  */
diff --git a/engines/mutationofjb/commands/saycommand.cpp b/engines/mutationofjb/commands/saycommand.cpp
index e63ceb198e..e99b4f20a6 100644
--- a/engines/mutationofjb/commands/saycommand.cpp
+++ b/engines/mutationofjb/commands/saycommand.cpp
@@ -33,8 +33,10 @@
 #include "common/debug-channels.h"
 
 /** @file
- * ("SM" | "SLM" | "NM" | "NLM") " " <lineToSay> ["<" <voiceFile> | "<!"]
- * <skipped> " " <lineToSay> ("<" <voiceFile> | "<!")
+ * <firstLine> { <CRLF> <additionalLine> }
+ *
+ * firstLine ::= ("SM" | "SLM" | "NM" | "NLM") " " <lineToSay> [ "<" <voiceFile> | "<!" ]
+ * additionalLine ::= <skipped> " " <lineToSay> ( "<" <voiceFile> | "<!" )
  *
  * Say command comes in four variants: SM, SLM, NM and NLM.
  * Note: In script files, they are usually written as *SM.
diff --git a/engines/mutationofjb/commands/seqcommand.h b/engines/mutationofjb/commands/seqcommand.h
index 6c969e935f..e37f77ff70 100644
--- a/engines/mutationofjb/commands/seqcommand.h
+++ b/engines/mutationofjb/commands/seqcommand.h
@@ -33,6 +33,9 @@ public:
 	virtual void transition(ScriptParseContext &parseCtx, Command *oldCommand, Command *newCommand, CommandParser *newCommandParser) override;
 };
 
+/**
+ * Base class for sequential commands.
+ */
 class SeqCommand : public Command {
 public:
 	SeqCommand() : _nextCommand(nullptr) {}
diff --git a/engines/mutationofjb/commands/talkcommand.cpp b/engines/mutationofjb/commands/talkcommand.cpp
index 5c7eb8e863..9857f38f9d 100644
--- a/engines/mutationofjb/commands/talkcommand.cpp
+++ b/engines/mutationofjb/commands/talkcommand.cpp
@@ -29,6 +29,17 @@
 
 #include "common/str.h"
 
+/** @file
+ * "TALK TO HIM" [ " " <mode> ]
+ *
+ * Begins interactive conversation defined by DefineStructCommand.
+ * The command supports multiple modes:
+ *   0 - normal mode,
+ *   1 - Ray and Buttleg mode (two responders),
+ *   2 - unknown (unused) mode,
+ *   3 - carnival ticket seller mode (special animation).
+ */
+
 namespace MutationOfJB {
 
 bool TalkCommandParser::parse(const Common::String &line, ScriptParseContext &, Command *&command) {