Improve Javadoc

wendelinwemhoener · wendelinwemhoener · commit f7c2ea7f3599 · 2023-11-12T14:05:16.000+08:00
diff --git a/data/flashcards/flashcard.txt b/data/flashcards/flashcard.txt
@@ -1,8 +1,2 @@
-3 | cs2113 | software enginnering | 3 
-5 | Hello | Duke | 4 
-7 | Hello | Duke | 4 
-9 | id | checker | 6 
-10 | id increases | correctly | 5 
-11 | f | dfdf | 5 
-12 | dfdf |  | 5 
-13 | 1 | j | 5 
+14 | dfdf | a | 5 
+15 | now | you can see me | 5 
diff --git a/src/main/java/seedu/duke/Duke.java b/src/main/java/seedu/duke/Duke.java
@@ -15,6 +15,9 @@ public static void main(String[] args) {
         new Duke().run();
     }
 
+    /**
+     * Starts a REPL session where commands are inputted and then processed.
+     */
     private void run() {
         FlashcardComponent fc = new FlashcardComponent();
         CalendarManager cm = new CalendarManager(new ArrayList<>());
@@ -29,9 +32,13 @@ private void run() {
 
             if (fc.isResponsible(input)) {
                 fc.processInput(input);
+                continue;
             } else if (cm.isResponsible(input)) {
                 cm.processInput(input);
-            } else if (input.toLowerCase().strip().equals("exit")) {
+                continue;
+            }
+
+            if (input.toLowerCase().strip().equals("exit")) {
                 System.out.println("    You are exiting TaskLinker! Bye!");
                 break;
             } else if (input.toLowerCase().strip().equals("help")) {
@@ -55,6 +62,8 @@ private void printHelp() {
             "list flashcards",
             "create flashcard",
             "review flashcards",
+            "delete flashcard",
+            "delete all flashcards",
             "help",
             "add event",
             "add goal event",
diff --git a/src/main/java/seedu/duke/flashcard/Flashcard.java b/src/main/java/seedu/duke/flashcard/Flashcard.java
@@ -28,6 +28,8 @@ public Flashcard(String frontText, String backText) {
 
         globalMaxId += 1;
         id = globalMaxId;
+
+        assert globalMaxId >= id : "No id must be bigger than globalMaxId";
     }
 
     /**
diff --git a/src/main/java/seedu/duke/flashcard/FlashcardCommandParser.java b/src/main/java/seedu/duke/flashcard/FlashcardCommandParser.java
@@ -22,7 +22,7 @@ public class FlashcardCommandParser {
      * @return The FlashcardCommand corresponding to input
      */
     public FlashcardCommand parseInput(String input) {
-        assert input != null : "input is null";
+        assert input != null : "input must not be null";
 
         input = input.toLowerCase().strip();
 
diff --git a/src/main/java/seedu/duke/flashcard/FlashcardComponent.java b/src/main/java/seedu/duke/flashcard/FlashcardComponent.java
@@ -63,6 +63,8 @@ public FlashcardUi getUi(){
      * @return Whether FlashcardComponent is responsible for handling the input.
      */
     public boolean isResponsible(String input) {
+        assert input != null : "input must not be null";
+
         FlashcardCommand command = parser.parseInput(input);
 
         if (command instanceof UnknownCommand) {
@@ -78,6 +80,8 @@ public boolean isResponsible(String input) {
      * @param input The text inputted by the user.
      */
     public void processInput(String input) {
+        assert input != null : "input must not be null";
+
         FlashcardCommand command = parser.parseInput(input);
         assert !(command instanceof UnknownCommand) : "Command cannot be " +
                 "unknown";
diff --git a/src/main/java/seedu/duke/flashcard/FlashcardList.java b/src/main/java/seedu/duke/flashcard/FlashcardList.java
@@ -47,6 +47,8 @@ public void add(Flashcard flashcard) {
      */
     public void deleteAllFlashcards() {
         flashcards.clear();
+
+        assert flashcards.size() == 0 : "flashcardList should be empty now";
     }
 
     /**
diff --git a/src/main/java/seedu/duke/flashcard/FlashcardUi.java b/src/main/java/seedu/duke/flashcard/FlashcardUi.java
@@ -21,6 +21,8 @@ public class FlashcardUi {
      */
     public FlashcardUi(FlashcardList flashcardList) {
         scanner = new Scanner(System.in);
+
+        assert flashcardList != null : "flashcardList cannot be null";
         this.flashcardList = flashcardList;
     }
 
diff --git a/src/main/java/seedu/duke/flashcard/command/CreateFlashcardCommand.java b/src/main/java/seedu/duke/flashcard/command/CreateFlashcardCommand.java
@@ -21,27 +21,12 @@ public class CreateFlashcardCommand extends FlashcardCommand {
      * @param flashcardList Which flashcards to perform actions on.
      */
     public void execute(Scanner scanner, FlashcardList flashcardList) {
-        System.out.print("    Enter the front page text: ");
-        String frontPageText = scanner.nextLine();
+        assert scanner != null : "Must be a valid Scanner instance";
+        assert flashcardList != null : "Must be a valid FlashcardList " +
+                "instance";
 
-        while (frontPageText.strip().equals("")) {
-            System.out.println("        Invalid input! The front text must " +
-                    "contain at least one letter or digit!");
-
-            System.out.print("    Enter the front page text: ");
-            frontPageText = scanner.nextLine();
-        }
-
-        System.out.print("    Enter the back page text: ");
-        String backPageText = scanner.nextLine();
-
-        while (backPageText.strip().equals("")) {
-            System.out.println("        Invalid input! The back text must " +
-                    "contain at least one letter or digit!");
-
-            System.out.print("    Enter the back page text: ");
-            backPageText = scanner.nextLine();
-        }
+        String frontPageText = getInputUntilNonEmptyString(scanner, "front");
+        String backPageText = getInputUntilNonEmptyString(scanner, "back");
 
         Flashcard flashcard = new Flashcard(frontPageText, backPageText);
 
@@ -51,4 +36,31 @@ public void execute(Scanner scanner, FlashcardList flashcardList) {
         System.out.println("    Success! Flashcard has been added to your " +
                 "collection.");
     }
+
+    /**
+     * Gets a user input for a flashcard, making sure that it is non-empty.
+     *
+     * @param scanner To get user input.
+     * @param flashcardSide Which side of the flashcard (front or back) is
+     *                      targeted.
+     * @return The user input for the specified flashcardSide.
+     */
+    private String getInputUntilNonEmptyString(Scanner scanner,
+                                               String flashcardSide) {
+        System.out.print("    Enter the " + flashcardSide + " page text: ");
+        String text = scanner.nextLine();
+
+        while (text.strip().equals("")) {
+            System.out.println("        Invalid input! The " + flashcardSide +
+                    " text must contain at least one letter or digit!");
+
+            System.out.print("    Enter the " + flashcardSide
+                    + " page text: ");
+            text = scanner.nextLine();
+        }
+
+        assert text != null : "Must be a non-null string";
+        assert (!text.strip().equals("")) : "Must be a non-empty string";
+        return text;
+    }
 }
diff --git a/src/main/java/seedu/duke/flashcard/command/DeleteAllFlashcardsCommand.java b/src/main/java/seedu/duke/flashcard/command/DeleteAllFlashcardsCommand.java
@@ -19,5 +19,7 @@ public void execute(Scanner scanner, FlashcardList flashcardList) {
 
         System.out.println("    All your flashcards have been successfully " +
                 "deleted .");
+
+        assert flashcardList.isEmpty() : "flashcardList must be empty";
     }
 }
diff --git a/src/main/java/seedu/duke/flashcard/command/DeleteFlashcardCommand.java b/src/main/java/seedu/duke/flashcard/command/DeleteFlashcardCommand.java
@@ -6,19 +6,31 @@
 
 import java.util.Scanner;
 
+/**
+ * This command allows deleting a specific flashcard (by its id).
+ */
 public class DeleteFlashcardCommand extends DualFlashcardCommand {
-
     public DeleteFlashcardCommand(String input) {
         this.input = input;
         beginnerCommandLength = 2;
         expertCommandLength = 3;
         syntaxString = "delete flashcard FLASHCARD_ID";
     }
 
+    /**
+     * Starts an interactive process for deleting a flashcard by its id.
+     * The user is prompted to enter the id; and then it is deleted.
+     *
+     * @param scanner Scanner for getting user input.
+     * @param flashcardList FlashcardList from which to delete.
+     */
     protected void executeBeginnerMode(Scanner scanner,
                                     FlashcardList flashcardList) {
-        System.out.println("    Enter id of the flashcard you want to delete:" +
-                " ");
+        assert flashcardList != null : "Must be a valid flashcardList " +
+                "instance";
+
+        System.out.println("    Enter id of the flashcard you want to " +
+                "delete: ");
 
         String input = scanner.nextLine();
         int flashcardId;
@@ -33,9 +45,19 @@ protected void executeBeginnerMode(Scanner scanner,
         deleteFlashcardById(flashcardId, flashcardList);
     }
 
+    /**
+     * Allows deleting a flashcard whose id is already known.
+     *
+     * @param scanner Scanner for getting user input.
+     * @param flashcardList FlashcardList from which to delete.
+     */
     protected void executeExpertMode(Scanner scanner,
                                   FlashcardList flashcardList) {
+        assert flashcardList != null : "Must be a valid flashcardList " +
+                "instance";
+
         String[] commandParts = input.split(" ");
+        assert commandParts.length != 0 : "must contain command parts";
 
         try {
             int flashcardId = Integer.parseInt(commandParts[2]);
@@ -45,15 +67,22 @@ protected void executeExpertMode(Scanner scanner,
         }
     }
 
+    /**
+     * Tries to delete a flashcard by id and prints whether it succeeded.
+     *
+     * @param flashcardId The id of the flashcard to delete.
+     * @param flashcardList The list of all known flashcards.
+     */
     private void deleteFlashcardById(int flashcardId, FlashcardList flashcardList) {
         boolean deletionWasSuccessful =
                 flashcardList.deleteFlashcardById(flashcardId);
 
         if (deletionWasSuccessful) {
-            System.out.println("    Flashcard with id " + flashcardId + " has been " +
-                    "successfully deleted.");
+            System.out.println("    Flashcard with id " + flashcardId +
+                    " has been successfully deleted.");
         } else {
-            System.out.println("    Couldn't find a flashcard with id " + flashcardId);
+            System.out.println("    Couldn't find a flashcard with id "
+                    + flashcardId);
             System.out.println("    No deletion has been performed. Please " +
                     "try again with a valid id.");
         }
diff --git a/src/main/java/seedu/duke/flashcard/review/RandomReviewMode.java b/src/main/java/seedu/duke/flashcard/review/RandomReviewMode.java
@@ -9,20 +9,37 @@
 import java.util.ArrayList;
 import java.util.Random;
 
+/**
+ * Review mode that randomly picks flashcards to review.
+ *
+ * This mode doesn't allow adjusting the difficulty of the reviewed flashcards.
+ */
 public class RandomReviewMode extends ReviewMode {
     public RandomReviewMode(FlashcardList flashcardList) {
         super(flashcardList);
     }
 
+    /**
+     * Identifies the instance as a random review mode instance.
+     *
+     * @return Textual description that this is the random review mode.
+     */
     public String getReviewModeName() {
         return "random review mode";
     }
 
+    /**
+     * Chooses a random flashcard to be reviewed next.
+     *
+     * @return The next flashcard to review.
+     */
     protected Flashcard pickFlashcard() {
         ArrayList<Flashcard> flashcards = flashcardList.getFlashcards();
 
         SecureRandom random = new SecureRandom();
 
+        assert random != null : "must be valid SecureRandom instance";
+
         return flashcards.get(random.nextInt(flashcards.size()));
     }
 }
diff --git a/src/main/java/seedu/duke/flashcard/review/ReviewMode.java b/src/main/java/seedu/duke/flashcard/review/ReviewMode.java
@@ -9,16 +9,36 @@
 import java.util.Arrays;
 import java.util.Scanner;
 
+/**
+ * Base class for implementing different kinds of flashcard reviews.
+ *
+ * Provides functionalities to easily review flashcards that can be used by
+ * subclasses as building blocks to implement specific kinds (e.g. random or
+ * difficulty-based) reviews.
+ */
 public abstract class ReviewMode {
     protected FlashcardList flashcardList;
 
     public ReviewMode(FlashcardList flashcardList) {
+        assert flashcardList != null : "flashcardList cannot be null";
         this.flashcardList = flashcardList;
     }
 
+    /**
+     * Abstract method to allow subclasses to identify themselves easily.
+     *
+     * @return Textual description of what kind of review mode this class is.
+     */
     public abstract String getReviewModeName();
 
+    /**
+     * Starts and executes a flashcard review session.
+     *
+     * @param scanner For getting input from user.
+     */
     public void startReviewSession(Scanner scanner) {
+        assert scanner != null : "must be a valid Scanner instance";
+
         System.out.println("    You have started a review session in "
                 + getReviewModeName() + System.lineSeparator());
 
@@ -34,7 +54,8 @@ public void startReviewSession(Scanner scanner) {
             printFlashcardFrontTextPrompt(flashcardToReview);
 
             String input = scanner.nextLine();
-            boolean shouldTerminate = input.startsWith("quit") || input.equals("q");
+            boolean shouldTerminate =
+                    input.strip().equals("quit") || input.strip().equals("q");
             if (shouldTerminate) {
                 break;
             }
@@ -50,11 +71,24 @@ public void startReviewSession(Scanner scanner) {
         System.out.println("    Success! You have ended this review session.");
     }
 
+    /**
+     * Allows subclasses to choose which flashcard to review next.
+     *
+     * @return The next flashcard to review.
+     */
     protected abstract Flashcard pickFlashcard();
 
+    /**
+     * Prints front of a flashcard and prompts the user to think of its back.
+     *
+     * @param flashcardToReview The flashcard currently being reviewed.
+     */
     protected void printFlashcardFrontTextPrompt(Flashcard flashcardToReview) {
+        assert flashcardToReview != null : "must be a valid Flashcard instance";
+
         System.out.println("    " + "-".repeat(76));
-        System.out.println("    The front text is: " + flashcardToReview.getFrontText());
+        System.out.println("    The front text is: "
+                + flashcardToReview.getFrontText());
         System.out.println();
 
         System.out.println("    [Think of the answer (the back text) in " +
@@ -64,8 +98,23 @@ protected void printFlashcardFrontTextPrompt(Flashcard flashcardToReview) {
                 "review session]");
     }
 
+    /**
+     * Lets the user rate the difficulty of a flashcard and then adjusts it.
+     *
+     * Depending on the rating given by the user, the flashcard difficulty is
+     * increased, kept constant or decreased. If the user rates the flashcard
+     * as easy, difficulty is decreased by one; if the user rates it as
+     * medium hard, difficulty is kept unchanges; and if the user rates it as
+     * hard, difficulty is increased by one.
+     *
+     * @param scanner To get user input.
+     * @param flashcard The flashcard currently under review.
+     */
     protected void letUserRateReviewDifficulty(Scanner scanner,
                                                Flashcard flashcard) {
+        assert flashcard != null : "must be a valid Flashcard instance";
+        assert scanner != null : "must be a valid Scanner instance";
+
         System.out.println("    How hard was it to remember the back page of " +
                 "this flashcard?");
         System.out.println("    Press <E> if it was easy, <M> if it was " +
diff --git a/src/main/java/seedu/duke/flashcard/review/SpacedRepetitionReviewMode.java b/src/main/java/seedu/duke/flashcard/review/SpacedRepetitionReviewMode.java

Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,8 @@ public Flashcard(String frontText, String backText) {`
`28`	`28`
`29`	`29`	`globalMaxId += 1;`
`30`	`30`	`id = globalMaxId;`
	`31`	`+`
	`32`	`+ assert globalMaxId >= id : "No id must be bigger than globalMaxId";`
`31`	`33`	`}`
`32`	`34`
`33`	`35`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -47,6 +47,8 @@ public void add(Flashcard flashcard) {`
`47`	`47`	`*/`
`48`	`48`	`public void deleteAllFlashcards() {`
`49`	`49`	`flashcards.clear();`
	`50`	`+`
	`51`	`+ assert flashcards.size() == 0 : "flashcardList should be empty now";`
`50`	`52`	`}`
`51`	`53`
`52`	`54`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,8 @@ public class FlashcardUi {`
`21`	`21`	`*/`
`22`	`22`	`public FlashcardUi(FlashcardList flashcardList) {`
`23`	`23`	`scanner = new Scanner(System.in);`
	`24`	`+`
	`25`	`+ assert flashcardList != null : "flashcardList cannot be null";`
`24`	`26`	`this.flashcardList = flashcardList;`
`25`	`27`	`}`
`26`	`28`
Original file line number	Diff line number	Diff line change
`@@ -19,5 +19,7 @@ public void execute(Scanner scanner, FlashcardList flashcardList) {`
`19`	`19`
`20`	`20`	`System.out.println(" All your flashcards have been successfully " +`
`21`	`21`	`"deleted .");`
	`22`	`+`
	`23`	`+ assert flashcardList.isEmpty() : "flashcardList must be empty";`
`22`	`24`	`}`
`23`	`25`	`}`