From 1b4b8c7e5bbe05f05f6cfc7aa16ad0570af4f2ca Mon Sep 17 00:00:00 2001 From: Pacien TRAN-GIRARD Date: Sun, 23 Feb 2014 19:41:18 +0100 Subject: Complete Javadoc comments --- src/esieequest/Command.java | 37 +++++++++++++++++++++++++++++++++++++ src/esieequest/Game.java | 37 +++++++++++++++++++++++++++++++++++++ src/esieequest/Main.java | 5 +++++ src/esieequest/Room.java | 12 ++++++++++-- src/esieequest/package-info.java | 5 +++++ 5 files changed, 94 insertions(+), 2 deletions(-) create mode 100644 src/esieequest/package-info.java (limited to 'src') 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 . + * + * If the command had only one word, then the second word is . + * * @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 that direction. + * * @author Pacien TRAN-GIRARD * @author Benoit LUBRANO DI SBARAGLIONE * @@ -17,8 +22,11 @@ public class Room { private HashMap aExits; /** - * Create a room described "description "Initially, it has no exits. - * "description" is something like "a kitchen" or "an open courtyard". + * Create a room described "description". Initially, it has no exits. + * "description" is something like "a kitchen" or "an open court yard". + * + * @param description + * The room's description. */ public Room(final String pDescription) { this.aDescription = pDescription; diff --git a/src/esieequest/package-info.java b/src/esieequest/package-info.java new file mode 100644 index 0000000..a5a042f --- /dev/null +++ b/src/esieequest/package-info.java @@ -0,0 +1,5 @@ +/** + * "ESIEEquest" is a very simple, text based adventure game. + */ +package esieequest; + -- cgit v1.2.3