Merge pull request #63 from CSC207-2022F-UofT/xgao28_userjoin_javadoc

[+] Added javadoc for userjoin use case.

src/main/java/billgates/interface_adapters/UserJoinUpdatable.java

@@ -2,8 +2,21 @@
 
 import billgates.use_cases.user_join.UserJoinViewModel;
 
+/**
+ * Clean Architecture Layer: Interface Adapters
+ * An interface represents that a view is updatable with respect to the <code>UserJoinViewModel</code>.
+ * The purpose of this interface is dependency inversion.
+ *
+ * @author Xinxiang
+ * @see UserJoinViewModel
+ */
 public interface UserJoinUpdatable {
 
+    /**
+     * Updates the table according to the <code>viewModel</code>.
+     *
+     * @param viewModel a data structure specifying the data required for this update.
+     */
     void view(UserJoinViewModel viewModel);
 
 }

src/main/java/billgates/use_cases/user_join/UserJoinController.java

@@ -1,5 +1,14 @@
 package billgates.use_cases.user_join;
 
+/**
+ * Clean Architecture Layer: Interface Adapters
+ * This class serves as the controller of the User Join Use Case.
+ * It is only responsible for accepting the input (<code>username</code>,
+ * <code>password</code>) from the user and invoke the corresponding use case.
+ *
+ * @author Xinxiang
+ * @see UserJoinInputPort
+ */
 public class UserJoinController {
 
     private final UserJoinInputPort useCase;

src/main/java/billgates/use_cases/user_join/UserJoinInputPort.java

@@ -1,5 +1,25 @@
 package billgates.use_cases.user_join;
 
+/**
+ * Clean Architecture Layer: Application Business Rules
+ * An input port for the User Join use case.
+ *
+ * @author Xinxiang
+ * @see UserJoinUseCase
+ */
 public interface UserJoinInputPort {
+
+    /**
+     * This method will detect 3 different scenarios from the
+     * <code>UserJoinRequestModel</code> model and take following actions:
+     * Case 1: If the username is not in the database,
+     * a new user is created and recorded in the database. i.e, register a new user.
+     * Case 2: If the username is in the database and the password matches,
+     * the corresponding user is logged in.
+     * Case 3: If the username is in the database and the password doesn't match,
+     * either the username is not valid for a register or the password is incorrect,
+     * and the corresponding user is not logged in.
+     * @param model the model that needs certain actions above.
+     */
     void join(UserJoinRequestModel model);
 }

src/main/java/billgates/use_cases/user_join/UserJoinOutputPort.java

@@ -1,5 +1,21 @@
 package billgates.use_cases.user_join;
 
+/**
+ * Clean Architecture Layer: Application Business Rules
+ * An output port for the User Join use case.
+ * The purpose of this interface is dependency inversion.
+ *
+ * @author Xinxiang
+ * @see UserJoinUseCase
+ * @see UserJoinPresenter
+ */
 public interface UserJoinOutputPort {
+
+    /**
+     * Converts the data in model to a GUI-friendly format and
+     * updates the GUI correspondingly.
+     *
+     * @param model the model to convert.
+     */
     void display(UserJoinResponseModel model);
 }

src/main/java/billgates/use_cases/user_join/UserJoinPresenter.java

@@ -2,6 +2,14 @@
 
 import billgates.interface_adapters.UserJoinUpdatable;
 
+/**
+ * Clean Architecture Layer: Interface Adapters
+ * A presenter in Clean Architecture for the User Join use case.
+ * This presenter is implemented based on the MVC architecture.
+ *
+ * @author Xinxiang
+ * @see UserJoinUpdatable
+ */
 public class UserJoinPresenter implements UserJoinOutputPort {
 
     private UserJoinUpdatable view;

src/main/java/billgates/use_cases/user_join/UserJoinRequestModel.java

@@ -1,5 +1,16 @@
 package billgates.use_cases.user_join;
 
+/**
+ * Clean Architecture Layer: Application Business Rules
+ * A request model of the User Join use case.
+ * It is used to transfer input username and password as a whole
+ * from the controller to the use case.
+ *
+ * @author Xinxiang
+ * @see UserJoinInputPort
+ * @see UserJoinUseCase
+ * @see UserJoinController
+ */
 public class UserJoinRequestModel {
     private String username;
     private String password;

src/main/java/billgates/use_cases/user_join/UserJoinResponseModel.java

@@ -1,5 +1,15 @@
 package billgates.use_cases.user_join;
 
+/**
+ * Clean Architecture Layer: Application Business Rules
+ * A response model of the User Join use case.
+ * It is used to transfer data from the use case to the presenter.
+ *
+ * @author Xinxiang
+ * @see UserJoinUseCase
+ * @see UserJoinOutputPort
+ * @see UserJoinPresenter
+ */
 public class UserJoinResponseModel {
 
     private boolean isJoined;

src/main/java/billgates/use_cases/user_join/UserJoinUseCase.java

@@ -6,8 +6,26 @@
 
 import java.util.List;
 
+/**
+ * Clean Architecture Layer: Application Business Rules
+ * A concrete implementation of the <code>UserJoinInputPort</code>.
+ *
+ * @author Xinxiang, Scott, Charlotte
+ * @see UserJoinInputPort
+ * @see UserJoinPresenter
+ * @see UserJoinRequestModel
+ */
+
 public class UserJoinUseCase implements UserJoinInputPort {
+
+    /**
+     * The presenter for converting the response model to a view model.
+     */
     private final DatabaseGateway gateway;
+
+    /**
+     * The database gateway for input/output with the database.
+     */
     private final UserJoinOutputPort outputPort;
 
     public UserJoinUseCase(DatabaseGateway gateway, UserJoinOutputPort outputPort) {

src/main/java/billgates/use_cases/user_join/UserJoinViewModel.java

@@ -1,8 +1,22 @@
 package billgates.use_cases.user_join;
 
+/**
+ * Clean Architecture Layer: Interface Adapters
+ * A view model holding information for the GUI to display.
+ *
+ * @author Xinxiang
+ * @see billgates.interface_adapters.UserJoinUpdatable
+ * @see UserJoinPresenter
+ */
 public class UserJoinViewModel {
 
+    /**
+     * Whether the user is joined.
+     */
     private boolean isJoined;
+    /**
+     * The reason that the view model is presented.
+     */
     private String reasonRejected;
 
     public UserJoinViewModel(boolean isJoined, String reasonRejected) {