Merge pull request #163 from devondragon/issue-155-Fix-inaccurate-Javadoc-on-confirmRegistration-method-on-the-UserActionController

Fix inaccurate Javadoc on confirmRegistration method and other Javadoc improvements

Author: devondragon

src/main/java/com/digitalsanctuary/spring/user/controller/UserActionController.java

@@ -89,13 +89,13 @@ public ModelAndView showChangePasswordPage(final HttpServletRequest request, fin
 	}
 
 	/**
-	 * Validate a forgot password token link from an email, and if valid, show the
-	 * registration success page.
+	 * Validates a registration token received from an email link, and if valid,
+	 * confirms the user's registration and redirects to the registration success page.
 	 *
-	 * @param request the request
-	 * @param model   the model
-	 * @param token   the token
-	 * @return the model and view
+	 * @param request the HTTP request
+	 * @param model   the model map
+	 * @param token   the verification token to validate
+	 * @return the model and view for redirection
 	 * @throws UnsupportedEncodingException the unsupported encoding exception
 	 */
 	@GetMapping("${user.security.registrationConfirmURI:/user/registrationConfirm}")

src/main/java/com/digitalsanctuary/spring/user/service/UserService.java

@@ -34,17 +34,12 @@
 import lombok.extern.slf4j.Slf4j;
 
 /**
- * Service class for managing users. It includes methods for user authentication, registration, deletion, password management, role assignment, and
- * related operations. This class also interacts with the user repository and session registry to perform its tasks.
+ * Service class for managing users. Provides methods for user registration, authentication, password management, and user-related operations. This
+ * class is transactional and uses various repositories and services for its operations.
  *
  * <p>
  * This class is transactional, meaning that any failure causes the entire operation to roll back to the previous state.
- *
- * @author Devon Hillard
- */
-/**
- * Service class for managing users. Provides methods for user registration, authentication, password management, and user-related operations. This
- * class is transactional and uses various repositories and services for its operations.
+ * </p>
  *
  * <p>
  * Dependencies:
@@ -112,6 +107,8 @@
  * <li>{@link Transactional}: Indicates that the class or methods should be transactional.</li>
  * <li>{@link Value}: Injects property values.</li>
  * </ul>
+ *
+ * @author Devon Hillard
  */
 @Slf4j
 @Service
@@ -199,10 +196,13 @@ public String getValue() {
 	private boolean sendRegistrationVerificationEmail;
 
 	/**
-	 * Register new user account.
+	 * Registers a new user account with the provided user data.
+	 * If the email already exists, throws a UserAlreadyExistException.
+	 * If sendRegistrationVerificationEmail is false, the user is enabled immediately.
 	 *
-	 * @param newUserDto the new user dto
-	 * @return the user
+	 * @param newUserDto the data transfer object containing the user registration information
+	 * @return the newly created user entity
+	 * @throws UserAlreadyExistException if an account with the same email already exists
 	 */
 	public User registerNewUserAccount(final UserDto newUserDto) {
 		TimeLogger timeLogger = new TimeLogger(log, "UserService.registerNewUserAccount");
@@ -371,12 +371,15 @@ public List<String> getUsersFromSessionRegistry() {
 	}
 
 	/**
-	 * Authenticates the given user without a password. The user is authenticated by loading their details, generating their authorities from their
-	 * roles and privileges, and storing these details in the security context and session. This is a potentially dangerous method to call, as it will
-	 * authenticate the user without requiring a password!!! We are using it here to allow us to authenticate a user after they have registered,
-	 * without requiring them to log in again.
+	 * Authenticates the given user without requiring a password. This method loads the user's details,
+	 * generates their authorities from their roles and privileges, and stores these details in the
+	 * security context and session.
+	 * 
+	 * <p><strong>SECURITY WARNING:</strong> This is a potentially dangerous method as it authenticates
+	 * a user without password verification. This method should only be used in specific controlled scenarios,
+	 * such as after successful email verification or OAuth authentication.</p>
 	 *
-	 * @param user The user to authenticate.
+	 * @param user The user to authenticate without password verification
 	 */
 	public void authWithoutPassword(User user) {
 		log.debug("UserService.authWithoutPassword: authenticating user: {}", user);

src/main/java/com/digitalsanctuary/spring/user/service/UserVerificationService.java

@@ -43,20 +43,21 @@ public User getUserByVerificationToken(final String verificationToken) {
     }
 
     /**
-     * Gets the verification token.
+     * Gets the verification token by its string value.
      *
-     * @param VerificationToken the verification token
-     * @return the verification token
+     * @param verificationToken the verification token string
+     * @return the verification token entity
      */
-    public VerificationToken getVerificationToken(final String VerificationToken) {
-        return tokenRepository.findByToken(VerificationToken);
+    public VerificationToken getVerificationToken(final String verificationToken) {
+        return tokenRepository.findByToken(verificationToken);
     }
 
     /**
-     * Generate new verification token.
+     * Generates a new verification token to replace an existing one.
+     * Useful for extending verification periods or re-sending verification emails.
      *
-     * @param existingVerificationToken the existing verification token
-     * @return the verification token
+     * @param existingVerificationToken the existing verification token string to replace
+     * @return the updated verification token entity with a new token value
      */
     public VerificationToken generateNewVerificationToken(final String existingVerificationToken) {
         VerificationToken vToken = tokenRepository.findByToken(existingVerificationToken);
@@ -77,10 +78,10 @@ public void createVerificationTokenForUser(final User user, final String token)
     }
 
     /**
-     * Validate verification token.
+     * Validates a user verification token.
      *
-     * @param token the token
-     * @return the string
+     * @param token the token to validate
+     * @return the token validation result (VALID, INVALID_TOKEN, or EXPIRED)
      */
     public UserService.TokenValidationResult validateVerificationToken(String token) {
         final VerificationToken verificationToken = tokenRepository.findByToken(token);