Complete Javadoc comments

5 files changed, 94 insertions, 2 deletions

diff --git a/src/esieequest/Command.java b/src/esieequest/Command.java
index de6b853..fd05930 100644
--- a/src/esieequest/Command.java
+++ b/src/esieequest/Command.java
@@ -3,6 +3,17 @@ package esieequest;
 /**
  * A text command that triggers an action in the game.
  * 
+ * This class holds information about a command that was issued by the user. A
+ * command currently consists of two strings: a command word and a second word
+ * (for example, if the command was "take map", then the two strings obviously
+ * are "take" and "map").
+ * 
+ * The way this is used is: Commands are already checked for being valid command
+ * words. If the user entered an invalid command (a word that is not known) then
+ * the command word is <null>.
+ * 
+ * If the command had only one word, then the second word is <null>.
+ * 
  * @author Pacien TRAN-GIRARD
  * @author Benoit LUBRANO DI SBARAGLIONE
  * 
@@ -12,23 +23,49 @@ public class Command {
         private String aCommandWord;
         private String aSecondWord;
 
+        /**
+         * Create a command object. First and second word must be supplied, but
+         * either one (or both) can be null.
+         * 
+         * @param firstWord
+         *            The first word of the command. Null if the command was not
+         *            recognised.
+         * @param secondWord
+         *            The second word of the command.
+         */
         public Command(final String pCommandWord, final String pSecondWord) {
                 this.aCommandWord = pCommandWord;
                 this.aSecondWord = pSecondWord;
         }
 
+        /**
+         * Return the command word (the first word) of this command. If the command
+         * was not understood, the result is null.
+         * 
+         * @return The command word.
+         */
         public String getCommandWord() {
                 return this.aCommandWord;
         }
 
+        /**
+         * @return The second word of this command. Returns null if there was no
+         *         second word.
+         */
         public String getSecondWord() {
                 return this.aSecondWord;
         }
 
+        /**
+         * @return true if this command was not understood.
+         */
         public boolean isUnknown() {
                 return this.aCommandWord == null;
         }
 
+        /**
+         * @return true if the command has a second word.
+         */
         public boolean hasSecondWord() {
                 return this.aSecondWord != null;
         }
diff --git a/src/esieequest/Game.java b/src/esieequest/Game.java
index bad0106..638c9b8 100644
--- a/src/esieequest/Game.java
+++ b/src/esieequest/Game.java
@@ -3,6 +3,10 @@ package esieequest;
 /**
  * The game engine.
  * 
+ * This class creates and initializes all the others: it creates all rooms,
+ * creates the parser and starts the game. It also evaluates and executes the
+ * commands that the parser returns.
+ * 
  * @author Pacien TRAN-GIRARD
  * @author Benoit LUBRANO DI SBARAGLIONE
  * 
@@ -12,6 +16,9 @@ public class Game {
         private Room aCurrentRoom;
         private Parser aParser;
 
+        /**
+         * Create the game and initialize its internal map.
+         */
         public Game() {
                 this.createRooms();
                 this.printWelcome();
@@ -19,6 +26,9 @@ public class Game {
                 this.play();
         }
 
+        /**
+         * Main play routine. Loops until end of play.
+         */
         private void play() {
                 aParser = new Parser();
                 boolean vFinished = false;
@@ -30,6 +40,9 @@ public class Game {
                 System.out.println("Thank you for playing. Good bye.");
         }
 
+        /**
+         * Create all the rooms and link their exits together.
+         */
         private void createRooms() {
                 // create rooms
                 Room vAmphitheaterSeat = new Room("in the amphitheater");
@@ -162,6 +175,10 @@ public class Game {
                 this.aCurrentRoom = vAmphitheaterSeat;
         }
 
+        /**
+         * Try to go in one direction. If there is an exit, enter the new room,
+         * otherwise print an error message.
+         */
         public void goRoom(final Command pCommand) {
                 if (!pCommand.hasSecondWord()) {
                         System.out.println("Go where?");
@@ -183,6 +200,9 @@ public class Game {
                 System.out.println(this.aCurrentRoom.getLongDescription());
         }
 
+        /**
+         * Print out the opening message for the player.
+         */
         private void printWelcome() {
                 System.out.println("Welcome to ESIEEquest");
                 System.out.println("ESIEEquest is a new, incredibly surprising adventure game.");
@@ -190,6 +210,10 @@ public class Game {
                 System.out.println("");
         }
 
+        /**
+         * Print out some help information. Here we print some stupid, cryptic
+         * message and a list of the command words.
+         */
         private void printHelp() {
                 System.out.println("You are lost. You are alone. ");
                 System.out.println("You wander around at the university.");
@@ -198,6 +222,12 @@ public class Game {
                 System.out.println("  go quit help");
         }
 
+        /**
+         * "Quit" was entered. Check the rest of the command to see whether we
+         * really quit the game.
+         * 
+         * @return true, if this command quits the game, false otherwise.
+         */
         private boolean quit(final Command pCommand) {
                 if (pCommand.hasSecondWord()) {
                         System.out.println("Quit what?");
@@ -206,6 +236,13 @@ public class Game {
                 return true;
         }
 
+        /**
+         * Given a command, process (that is: execute) the command.
+         * 
+         * @param command
+         *            The command to be processed.
+         * @return true If the command ends the game, false otherwise.
+         */
         private boolean processCommand(final Command pCommand) {
                 if (pCommand.getCommandWord() != null) {
                         switch (pCommand.getCommandWord()) {
diff --git a/src/esieequest/Main.java b/src/esieequest/Main.java
index 88e66c2..8cbea80 100755
--- a/src/esieequest/Main.java
+++ b/src/esieequest/Main.java
@@ -1,6 +1,11 @@
 package esieequest;
 
 /**
+ * The Main class
+ * 
+ * This class instantiates the game and makes it possible to run it via the
+ * command line.
+ * 
  * @author Pacien TRAN-GIRARD
  * @author Benoit LUBRANO DI SBARAGLIONE
  * 
diff --git a/src/esieequest/Room.java b/src/esieequest/Room.java
index 9d7f071..32adc90 100644
--- a/src/esieequest/Room.java
+++ b/src/esieequest/Room.java
@@ -6,6 +6,11 @@ import java.util.Set;
 /**
  * A room.
  * 
+ * A "Room" represents one location in the scenery of the game. It is connected
+ * to other rooms via exits. The exits are labelled north, east, south, west.
+ * For each direction, the room stores a reference to the neighboring room, or
+ * null if there is no exit in tha