Skip to content

Commit

Permalink
documentation fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@akmsw
akmsw committed Jun 21, 2023
1 parent 8a2fbae commit 1518739
Show file tree
Hide file tree
Showing 17 changed files with 162 additions and 206 deletions.
21 changes: 10 additions & 11 deletions src/main/java/armameeldoparti/Main.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ private Main() {
// ---------------------------------------- Main entry point ----------------------------------

/**
* Starts the program by initializing the fields needed along with
* the program's graphical properties, and making the main menu view visible.
* Starts the program by initializing the fields needed along with the program's graphical
* properties, and making the main menu view visible.
*
* @param args Program arguments (not used yet).
*/
Expand Down Expand Up @@ -98,19 +98,18 @@ private static void populatePlayersSets() {
/**
* Gets the number of players for each position per team using regular expressions.
*
* <p>{@code [CLMFG].+>.+}: Retrieves the lines that start with C, L, M, F, or W,
* followed by at least one '>' character (these are the lines that matters in the
* .pda file).
* <p>{@code [CLMFG].+>.+}: Retrieves the lines that start with C, L, M, F, or W, followed by at
* least one '>' character (these are the lines that matters in the .pda file).
*
* <p>{@code (?!(?<=X)\\d).}: Gets the part of the line that is not a number that we are
* interested in (the number would take the place of the X).
*
* <p>If the .pda file is modified in terms of the order of the important lines,
* it must be taken into account that Position.values()[index] trusts that what is found
* corresponds to the order in which the values in the Position enum are declared.
* Idem, if the order of the Position enum values are changed, it should be noted that
* Position.values()[index] trusts the order in which the data will be retrieved from the
* .pda file and, therefore, you should review the order of the important lines in the file.
* <p>If the .pda file is modified in terms of the order of the important lines, it must be taken
* into account that Position.values()[index] trusts that what is found corresponds to the order
* in which the values in the Position enum are declared. Idem, if the order of the Position enum
* values are changed, it should be noted that Position.values()[index] trusts the order in which
* the data will be retrieved from the .pda file and, therefore, you should review the order of
* the important lines in the file.
*/
private static void setPlayersDistribution() {
try (BufferedReader buff = new BufferedReader(
Expand Down
71 changes: 31 additions & 40 deletions src/main/java/armameeldoparti/controllers/AnchoragesController.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,8 @@ public AnchoragesController(@NonNull AnchoragesView anchoragesView) {
/**
* Resets the controlled view to its default values.
*
* <p>Clears every anchorage made, updating the text area
* and the state of the buttons, and the checkboxes that
* were selected whose players were not anchored, are deselected.
* <p>Clears every anchorage made, updating the text area and the state of the buttons, and the
* checkboxes that were selected whose players were not anchored, are deselected.
*/
@Override
public void resetView() {
Expand All @@ -73,11 +72,11 @@ public void updateCheckBoxesText() {
/**
* 'Finish' button event handler.
*
* <p>Checks if the necessary anchorages conditions are met.
* If so, it proceeds with the distribution.
* <p>Checks if the necessary anchorages conditions are met. If so, it proceeds with the
* distribution.
*
* @param parentComponent Graphical component where the dialogs associated
* with the event should be displayed.
* @param parentComponent Graphical component where the dialogs associated with the event should
* be displayed.
*/
public void finishButtonEvent(Component parentComponent) {
if (!validAnchoragesCombination()) {
Expand All @@ -92,11 +91,10 @@ public void finishButtonEvent(Component parentComponent) {
/**
* 'New anchorage' button event handler.
*
* <p>Checks if the necessary conditions to make a new anchorage
* are met. If so, it does it.
* <p>Checks if the necessary conditions to make a new anchorage are met. If so, it does it.
*
* @param parentComponent Graphical component where the dialogs associated
* with the event should be displayed.
* @param parentComponent Graphical component where the dialogs associated with the event should
* be displayed.
*/
public void newAnchorageButtonEvent(Component parentComponent) {
int playersToAnchorAmount = (int) ((AnchoragesView) getView()).getCheckBoxesMap()
Expand Down Expand Up @@ -140,8 +138,7 @@ public void newAnchorageButtonEvent(Component parentComponent) {
/**
* 'Delete last anchorage' button event handler.
*
* <p>Deletes the last anchorage made, updating the text area and the
* state of the buttons.
* <p>Deletes the last anchorage made, updating the text area and the state of the buttons.
*/
public void deleteLastAnchorageButtonEvent() {
deleteAnchorage(anchoragesAmount);
Expand All @@ -152,11 +149,11 @@ public void deleteLastAnchorageButtonEvent() {
/**
* 'Delete anchorage' button event handler.
*
* <p>Prompts the user for the number of the anchorage to delete,
* and removes it, updating the text area and the state of the buttons.
* <p>Prompts the user for the number of the anchorage to delete, and removes it, updating the
* text area and the state of the buttons.
*
* @param parentComponent Graphical component where the dialogs associated
* with the event should be displayed.
* @param parentComponent Graphical component where the dialogs associated with the event should
* be displayed.
*/
public void deleteAnchorageButtonEvent(Component parentComponent) {
String[] optionsDelete = new String[anchoragesAmount];
Expand Down Expand Up @@ -194,9 +191,8 @@ public void clearAnchoragesButtonEvent() {
/**
* 'Back' button event handler.
*
* <p>Makes the controlled view invisible, deletes every anchorage made,
* resets the controlled view to its default state and shows the names
* input view.
* <p>Makes the controlled view invisible, deletes every anchorage made, resets the controlled
* view to its default state and shows the names input view.
*/
public void backButtonEvent() {
hideView();
Expand Down Expand Up @@ -325,12 +321,9 @@ private void clearAnchorages() {
/**
* Deletes a specific anchorage.
*
* <p>The players that have the specified anchorage, now
* will have anchorage number 0.
* If the anchorage number to delete is not the last one,
* then the remaining players (from the chosen anchor + 1
* to anchoragesAmount) will have their anchorage number
* decreased by 1.
* <p>The players that have the specified anchorage, now will have anchorage number 0. If the
* anchorage number to delete is not the last one, then the remaining players (from the chosen
* anchor + 1 to anchoragesAmount) will have their anchorage number decreased by 1.
*
* @param anchorageToDelete Anchorage number to delete.
*/
Expand All @@ -349,10 +342,9 @@ private void deleteAnchorage(int anchorageToDelete) {
/**
* Changes the anchorage number of certain players.
*
* <p>If the replacement is 0 (an anchorage must be removed), then
* those players will be set as not-anchored, the players corresponding
* checkboxes will be visible and enabled again, and the anchored players
* amount will be decreased as needed.
* <p>If the replacement is 0 (an anchorage must be removed), then those players will be set as
* not-anchored, the players corresponding checkboxes will be visible and enabled again, and the
* anchored players amount will be decreased as needed.
*
* @param target Anchorage number to replace.
* @param replacement New anchorage number to set.
Expand Down Expand Up @@ -385,8 +377,8 @@ private void changeAnchorage(int target, int replacement) {
}

/**
* The checkboxes that were selected whose players were not anchored,
* are deselected. Then, shows the corresponding following view.
* The checkboxes that were selected whose players were not anchored, are deselected. Then, shows
* the corresponding following view.
*/
private void finish() {
hideView();
Expand All @@ -407,8 +399,8 @@ private void finish() {
}

/**
* Sets the corresponding anchorage number to the selected players.
* Then, unchecks their checkboxes and makes them invisible.
* Sets the corresponding anchorage number to the selected players. Then, unchecks their
* checkboxes and makes them invisible.
*
* @param cbSet Check boxes set with players checked.
*/
Expand Down Expand Up @@ -447,13 +439,12 @@ private void clearCheckBoxes() {
}

/**
* Checks if the selected players amount is at least 2 and
* at most MAX_PLAYERS_PER_ANCHORAGE.
* Checks if the selected players amount is at least 2 and at most MAX_PLAYERS_PER_ANCHORAGE.
*
* @param playersToAnchorAmount Checked players to anchor.
*
* @return Whether the checked players amount is at least 2
* and at most MAX_PLAYERS_PER_ANCHORAGE, or not.
* @return Whether the checked players amount is at least 2 and at most MAX_PLAYERS_PER_ANCHORAGE,
* or not.
*/
private boolean validChecksAmount(int playersToAnchorAmount) {
return playersToAnchorAmount <= Constants.MAX_PLAYERS_PER_ANCHORAGE
Expand All @@ -479,8 +470,8 @@ private boolean validCheckedPlayersPerPosition() {
*
* @param playersToAnchorAmount Checked players amount.
*
* @return Whether the selected players amount is at most the maximum allowed
* per anchorage, or not.
* @return Whether the selected players amount is at most the maximum allowed per anchorage
* or not.
*/
private boolean validAnchoredPlayersAmount(int playersToAnchorAmount) {
return anchoredPlayersAmount + playersToAnchorAmount <= Constants.MAX_ANCHORED_PLAYERS;
Expand Down
4 changes: 2 additions & 2 deletions src/main/java/armameeldoparti/controllers/Controller.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@
import lombok.Setter;

/**
* Abstract class that specifies the basic methods for
* interaction between controllers and their assigned views.
* Abstract class that specifies the basic methods for interaction between controllers and their
* assigned views.
*
* @author Bonino, Francisco Ignacio.
*
Expand Down
12 changes: 6 additions & 6 deletions src/main/java/armameeldoparti/controllers/HelpController.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,8 @@ public void resetView() {
/**
* 'Back' button event handler.
*
* <p>Resets the page to the beginning, makes the controlled view
* invisible and shows the main menu view.
* <p>Resets the page to the beginning, makes the controlled view invisible and shows the main
* menu view.
*/
public void backButtonEvent() {
hideView();
Expand All @@ -92,8 +92,8 @@ public void backButtonEvent() {
/**
* 'Next page' button event handler.
*
* <p>Increments the page number, updating the state of the buttons,
* the displayed page in the text area and the reading progress label.
* <p>Increments the page number, updating the state of the buttons, the displayed page in the
* text area and the reading progress label.
*/
public void nextPageButtonEvent() {
if (++currentPageNumber < TOTAL_PAGES - 1) {
Expand All @@ -110,8 +110,8 @@ public void nextPageButtonEvent() {
/**
* 'Previous page' button event handler.
*
* <p>Decrements the page number, updating the state of the buttons,
* the displayed page in the text area and the reading progress label.
* <p>Decrements the page number, updating the state of the buttons, the displayed page in the
* text area and the reading progress label.
*/
public void previousPageButtonEvent() {
if (--currentPageNumber > 0) {
Expand Down
6 changes: 2 additions & 4 deletions src/main/java/armameeldoparti/controllers/MainMenuController.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,7 @@ public void showView() {
/**
* 'Help' button event handler.
*
* <p>Makes the controlled view invisible
* and shows the help view.
* <p>Makes the controlled view invisible and shows the help view.
*/
public void helpButtonEvent() {
hideView();
Expand All @@ -62,8 +61,7 @@ public void helpButtonEvent() {
/**
* 'Start' button event handler.
*
* <p>Makes the controlled view invisible
* and shows the names input view.
* <p>Makes the controlled view invisible and shows the names input view.
*/
public void startButtonEvent() {
hideView();
Expand Down
46 changes: 20 additions & 26 deletions src/main/java/armameeldoparti/controllers/NamesInputController.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,7 @@ public NamesInputController(@NonNull NamesInputView namesInputView) {
/**
* Makes the controlled view visible.
*
* <p>Updates the view state according to the combobox
* initial state, and makes it visible.
* <p>Updates the view state according to the combobox initial state, and makes it visible.
*/
@Override
public void showView() {
Expand All @@ -69,8 +68,7 @@ public void showView() {
}

/**
* Resets the controlled view to its default values and
* makes it invisible.
* Resets the controlled view to its default values and makes it invisible.
*/
@Override
public void resetView() {
Expand All @@ -93,9 +91,8 @@ public void resetView() {
/**
* 'Back' button event handler.
*
* <p>Resets the controlled view to its default values,
* turns the anchorages flags to false, makes the
* controlled view invisible and shows the main menu view.
* <p>Resets the controlled view to its default values, turns the anchorages flags to false, makes
* the controlled view invisible and shows the main menu view.
*/
public void backButtonEvent() {
resetView();
Expand All @@ -109,12 +106,11 @@ public void backButtonEvent() {
/**
* 'Mix' button event handler.
*
* <p>Asks the user for the players distribution method, makes
* the controlled view invisible and shows the corresponding
* following view.
* <p>Asks the user for the players distribution method, makes the controlled view invisible and
* shows the corresponding following view.
*
* @param parentComponent Graphical component where the dialogs associated
* with the event should be displayed.
* @param parentComponent Graphical component where the dialogs associated with the event should
* be displayed.
*/
public void mixButtonEvent(Component parentComponent) {
int distribution = JOptionPane.showOptionDialog(
Expand Down Expand Up @@ -158,13 +154,13 @@ public void mixButtonEvent(Component parentComponent) {
/**
* Text fields input event handler.
*
* <p>Validates the user input with a regular expression that checks if the string
* contains only latin characters from A to Z including Ñ, uppercase or lowercase,
* with or without accent mark, with or without spaces.
* If the input is not valid or already exists, the program asks for a new input.
* <p>Validates the user input with a regular expression that checks if the string contains only
* latin characters from A to Z including Ñ, uppercase or lowercase, with or without accent mark,
* with or without spaces. If the input is not valid or already exists, the program asks for a new
* input.
*
* <p>If the input is valid, it will be applied as a player name in the players set
* corresponding to the combobox selected option.
* <p>If the input is valid, it will be applied as a player name in the players set corresponding
* to the combobox selected option.
*
* @param playerIndex The index of the player which name will be the text filed input.
* @param playersSet The set of players corresponding to the selected combobox option.
Expand Down Expand Up @@ -216,8 +212,8 @@ public void comboBoxEvent(@NonNull String selectedOption) {
/**
* Updates the text displayed in the read-only text area.
*
* <p>The players names are shown in the order they are positioned in their respective list.
* The order is the same of the positions enum.
* <p>The players names are shown in the order they are positioned in their respective list. The
* order is the same of the positions enum.
*/
private void updateTextArea() {
var wrapperCounter = new Object() {
Expand Down Expand Up @@ -257,7 +253,7 @@ private void updateTextArea() {
private void updateTextFields(@NonNull String selectedOption) {
JPanel leftPanel = ((NamesInputView) getView()).getLeftPanel();

// Removes the text fields from the view's left panel.
// Removes the text fields from the view's left panel
((NamesInputView) getView()).getTextFieldsMap()
.values()
.stream()
Expand Down Expand Up @@ -322,14 +318,12 @@ private boolean validString(@NonNull String string) {
}

/**
* Checks if the given name has at most MAX_NAME_LEN characters,
* is not empty or blank and if there isn't already a player
* with that name.
* Checks if the given name has at most MAX_NAME_LEN characters, is not empty or blank and if
* there isn't already a player with that name.
*
* @param name The name to validate.
*
* @return If the given name is valid according to
* the specified conditions.
* @return If the given name is valid according to the specified conditions.
*/
private boolean validName(@NonNull String name) {
return name.length() <= Constants.MAX_NAME_LEN
Expand Down
Loading

0 comments on commit 1518739

Please sign in to comment.