Add docstrings for all functions, classes, and entity fields

Author: Sporiff

src/main/java/org/openpodcastapi/opa/advice/GlobalExceptionHandler.java

@@ -16,32 +16,53 @@
 import java.time.Instant;
 import java.util.List;
 
+/// A global handler for common exceptions thrown by the application.
+///
+/// Where possible, controllers should throw their own exceptions.
+/// However, for common exceptions such as invalid parameters and
+/// not found entities, a global exception handler can be added.
 @RestControllerAdvice
 @RequiredArgsConstructor
 @Log4j2
 public class GlobalExceptionHandler {
+    /// Returns a 404 if a database entity is not found
+    ///
+    /// @param exception the thrown [EntityNotFoundException]
+    /// @return a [ResponseEntity] containing the error message
     @ExceptionHandler(EntityNotFoundException.class)
     @ResponseStatus(HttpStatus.NOT_FOUND)
-    public ResponseEntity<@NonNull String> handleEntityNotFoundException(EntityNotFoundException error) {
-        log.debug("{}", error.getMessage());
+    public ResponseEntity<@NonNull String> handleEntityNotFoundException(EntityNotFoundException exception) {
+        log.debug("{}", exception.getMessage());
         return ResponseEntity.notFound().build();
     }
 
+    /// Returns a 400 error when conflicting data is entered
+    ///
+    /// @param exception the thrown [DataIntegrityViolationException]
+    /// @return a [ResponseEntity] containing the error message
     @ExceptionHandler(DataIntegrityViolationException.class)
     @ResponseStatus(HttpStatus.BAD_REQUEST)
-    public ResponseEntity<@NonNull String> handleDataIntegrityViolationException(DataIntegrityViolationException e) {
-        return ResponseEntity.badRequest().body(e.getMessage());
+    public ResponseEntity<@NonNull String> handleDataIntegrityViolationException(DataIntegrityViolationException exception) {
+        return ResponseEntity.badRequest().body(exception.getMessage());
     }
 
+    /// Returns a 400 error when illegal arguments are passed
+    ///
+    /// @param exception the thrown [IllegalArgumentException]
+    /// @return a [ResponseEntity] containing the error message
     @ExceptionHandler(IllegalArgumentException.class)
     @ResponseStatus(HttpStatus.BAD_REQUEST)
-    public ResponseEntity<@NonNull String> handleIllegalArgumentException(IllegalArgumentException e) {
-        return ResponseEntity.badRequest().body(e.getMessage());
+    public ResponseEntity<@NonNull String> handleIllegalArgumentException(IllegalArgumentException exception) {
+        return ResponseEntity.badRequest().body(exception.getMessage());
     }
 
+    /// Returns a 400 error when invalid arguments are passed to an endpoint
+    ///
+    /// @param exception the thrown [MethodArgumentNotValidException]
+    /// @return a [ResponseEntity] containing the error message
     @ExceptionHandler(MethodArgumentNotValidException.class)
-    public ResponseEntity<@NonNull ValidationErrorResponse> handleValidationException(MethodArgumentNotValidException ex) {
-        List<ValidationErrorResponse.FieldError> errors = ex.getBindingResult().getFieldErrors().stream()
+    public ResponseEntity<@NonNull ValidationErrorResponse> handleValidationException(MethodArgumentNotValidException exception) {
+        List<ValidationErrorResponse.FieldError> errors = exception.getBindingResult().getFieldErrors().stream()
                 .map(fe -> new ValidationErrorResponse.FieldError(fe.getField(), fe.getDefaultMessage()))
                 .toList();
 

src/main/java/org/openpodcastapi/opa/advice/GlobalModelAttributeAdvice.java

@@ -9,10 +9,19 @@
 
 import java.security.Principal;
 
+/// A helper class for adding user information to requests.
+///
+/// This class is used to populate user details in templates
+/// and to ensure that a user is authenticated when viewing
+/// web pages.
 @Log4j2
 @ControllerAdvice
 public class GlobalModelAttributeAdvice {
 
+    /// Adds a boolean `isAuthenticated` property to the request model based on
+    /// whether the user is logged-in.
+    ///
+    /// @param model the [Model] attached to the request
     @ModelAttribute
     public void addAuthenticationFlag(Model model) {
         Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
@@ -21,6 +30,10 @@ public void addAuthenticationFlag(Model model) {
         model.addAttribute("isAuthenticated", isAuthenticated);
     }
 
+    /// Adds user details to the request model.
+    ///
+    /// @param principal the [Principal] representing the user
+    /// @param model     the [Model] attached to the request
     @ModelAttribute
     public void addUserDetails(Principal principal, Model model) {
         var username = principal != null ? principal.getName() : "Guest";

src/main/java/org/openpodcastapi/opa/auth/ApiBearerTokenAuthenticationConverter.java

@@ -6,6 +6,10 @@
 import org.springframework.security.web.authentication.AuthenticationConverter;
 import org.springframework.stereotype.Component;
 
+/// A converter that handles JWT-based auth for API requests.
+///
+/// This converter targets only the API endpoints at `/api`.
+/// Auth for the frontend is handled by Spring's form login.
 @Component
 public class ApiBearerTokenAuthenticationConverter implements AuthenticationConverter {
 
@@ -15,7 +19,7 @@ public class ApiBearerTokenAuthenticationConverter implements AuthenticationConv
     @Override
     public Authentication convert(HttpServletRequest request) {
 
-        String path = request.getRequestURI();
+        final var path = request.getRequestURI();
 
         // Don't authenticate the auth endpoints
         if (path.startsWith("/api/auth/")) {

src/main/java/org/openpodcastapi/opa/auth/ApiSecurityHandlers.java

@@ -6,9 +6,12 @@
 import org.springframework.security.web.access.AccessDeniedHandler;
 import org.springframework.stereotype.Component;
 
+/// Contains handlers for token-related errors on API endpoints
 @Component
 public class ApiSecurityHandlers {
     /// Returns an unauthorized response for unauthenticate API queries
+    ///
+    /// @return an unauthorized response with a JSON-formatted error message
     @Bean
     public AuthenticationEntryPoint apiAuthenticationEntryPoint() {
         return (_, response, authException) -> {
@@ -21,6 +24,8 @@ public AuthenticationEntryPoint apiAuthenticationEntryPoint() {
     }
 
     /// Returns a forbidden response for API queries
+    ///
+    /// @return a forbidden response with a JSON-formatted error message
     @Bean
     public AccessDeniedHandler apiAccessDeniedHandler() {
         return (_, response, exception) -> {

src/main/java/org/openpodcastapi/opa/auth/JwtAuthenticationProvider.java

@@ -18,12 +18,18 @@
 import java.nio.charset.StandardCharsets;
 import java.util.UUID;
 
+/// Handles provisioning and authenticating JWTs for API requests
 @Component
 public class JwtAuthenticationProvider implements AuthenticationProvider {
 
     private final UserRepository repository;
     private final SecretKey key;
 
+    /// Constructor with secret value provided in `.env` file
+    /// or environment variables.
+    ///
+    /// @param repository the [UserRepository] interface for user entities
+    /// @param secret     the secret value used to generate JWT values
     public JwtAuthenticationProvider(
             UserRepository repository,
             @Value("${jwt.secret}") String secret) {
@@ -36,25 +42,31 @@ public JwtAuthenticationProvider(
     public Authentication authenticate(Authentication authentication)
             throws AuthenticationException {
 
+        // Get the JWT token from the authentication header
         final var token = (String) authentication.getCredentials();
 
         try {
+            // Parse the JWT claims
             final var claims = Jwts.parser()
                     .verifyWith(key)
                     .build()
                     .parseSignedClaims(token)
                     .getPayload();
 
+            // Get the user's UUID from the claims subject
             final var uuid = UUID.fromString(claims.getSubject());
 
-            final var user = repository.getUserByUuid(uuid)
+            // Find the user entity
+            final var user = repository.findUserByUuid(uuid)
                     .orElseThrow(() -> new BadCredentialsException("User not found"));
 
+            // Configure the user details for the authenticated user
             final var details = new CustomUserDetails(
                     user.getId(), user.getUuid(), user.getUsername(),
                     user.getPassword(), user.getUserRoles()
             );
 
+            // Return the parsed token
             return new UsernamePasswordAuthenticationToken(
                     details, token, details.getAuthorities());
         } catch (Exception ex) {

src/main/java/org/openpodcastapi/opa/config/SecurityConfig.java

@@ -22,6 +22,7 @@
 import org.springframework.security.web.access.AccessDeniedHandler;
 import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
 
+/// Security configuration for the Spring application
 @Configuration
 @EnableWebSecurity
 @RequiredArgsConstructor
@@ -41,6 +42,14 @@ public class SecurityConfig {
             "/favicon.ico",
     };
 
+    /// API-related security configuration
+    ///
+    /// @param http                      the [HttpSecurity] object to be configured
+    /// @param jwtAuthenticationProvider the [JwtAuthenticationProvider] used to handle JWT auth
+    /// @param entryPoint                the entrypoint that commences the JWT auth
+    /// @param deniedHandler             the [AccessDeniedHandler] that handles auth failures
+    /// @param converter                 the [ApiBearerTokenAuthenticationConverter] that manages JWT validation
+    /// @return the configured [HttpSecurity] object
     @Bean
     @Order(1)
     public SecurityFilterChain apiSecurity(
@@ -79,6 +88,10 @@ public SecurityFilterChain apiSecurity(
         return http.build();
     }
 
+    /// Web-related security configuration
+    ///
+    /// @param http the [HttpSecurity] object to be configured
+    /// @return the configured [HttpSecurity] object
     @Bean
     @Order(2)
     public SecurityFilterChain webSecurity(HttpSecurity http) {
@@ -104,11 +117,19 @@ public SecurityFilterChain webSecurity(HttpSecurity http) {
                 .build();
     }
 
+    /// The default password encoder used for hashing and encoding user passwords and JWTs
+    ///
+    /// @return a configured [BCryptPasswordEncoder]
     @Bean
     public BCryptPasswordEncoder passwordEncoder() {
         return new BCryptPasswordEncoder();
     }
 
+    /// An authentication provider for password-based authentication
+    ///
+    /// @param userDetailsService the [UserDetailsService] for loading user data
+    /// @param passwordEncoder    the default password encoder
+    /// @return the configured [DaoAuthenticationProvider]
     @Bean
     public DaoAuthenticationProvider daoAuthenticationProvider(UserDetailsService userDetailsService,
                                                                BCryptPasswordEncoder passwordEncoder) {
@@ -117,11 +138,20 @@ public DaoAuthenticationProvider daoAuthenticationProvider(UserDetailsService us
         return provider;
     }
 
+    /// An authentication provider for JWT-based authentication
+    ///
+    /// @param provider a configured [JwtAuthenticationProvider]
+    /// @return a configured [ProviderManager] that uses the JWT auth provider
+    /// @see JwtAuthenticationProvider for provider details
     @Bean(name = "jwtAuthManager")
     public AuthenticationManager jwtAuthenticationManager(JwtAuthenticationProvider provider) {
         return new ProviderManager(provider);
     }
 
+    /// An authentication provider for API POST login
+    ///
+    /// @param daoProvider a configured [DaoAuthenticationProvider]
+    /// @return a configured [ProviderManager] that uses basic username/password auth
     @Bean(name = "apiLoginManager", defaultCandidate = false)
     public AuthenticationManager apiLoginAuthenticationManager(
             DaoAuthenticationProvider daoProvider) {

src/main/java/org/openpodcastapi/opa/config/WebConfig.java

@@ -6,23 +6,32 @@
 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 
+/// Configuration for the web interface
 @Configuration
 public class WebConfig implements WebMvcConfigurer {
     @Override
     public void addResourceHandlers(ResourceHandlerRegistry registry) {
+        // Additional CSS storage
         registry
                 .addResourceHandler("/css/**")
                 .addResourceLocations("classpath:/static/css/");
 
+        // Additional JavaScript storage
         registry
                 .addResourceHandler("/js/**")
                 .addResourceLocations("classpath:/static/js/");
 
+        // The hosted documentation
         registry
                 .addResourceHandler("/docs/**")
                 .addResourceLocations("classpath:/static/docs/");
     }
 
+    /// Informs Spring to use Thymeleaf Layout Dialect for composing Thymeleaf templates
+    ///
+    /// See [Thymeleaf Layout Dialect](https://ultraq.github.io/thymeleaf-layout-dialect/) for more information
+    ///
+    /// @return the configured [LayoutDialect]
     @Bean
     public LayoutDialect layoutDialect() {
         return new LayoutDialect();

src/main/java/org/openpodcastapi/opa/controllers/api/AuthController.java

@@ -18,13 +18,20 @@
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RestController;
 
+/// Controllers for API-based authentication
 @RestController
 @Log4j2
 public class AuthController {
     private final TokenService tokenService;
     private final UserRepository userRepository;
     private final AuthenticationManager authenticationManager;
 
+    /// Constructs the controller with the correct [AuthenticationManager]
+    ///
+    /// @param tokenService          the [TokenService] used to manage auth tokens
+    /// @param userRepository        the [UserRepository] used to manage user entity interaction
+    /// @param authenticationManager the [AuthenticationManager] used to handle auth
+    /// @see org.openpodcastapi.opa.config.SecurityConfig#apiLoginAuthenticationManager
     public AuthController(
             TokenService tokenService,
             UserRepository userRepository,
@@ -35,7 +42,10 @@ public AuthController(
         this.authenticationManager = authenticationManager;
     }
 
-    // === Login endpoint ===
+    /// The API login endpoint. Accepts a basic username/password combination to authenticate.
+    ///
+    /// @param loginRequest the [AuthDTO.LoginRequest] containing the user's credentials
+    /// @return a [ResponseEntity] containing a [AuthDTO.LoginSuccessResponse]
     @PostMapping("/api/auth/login")
     public ResponseEntity<AuthDTO.@NonNull LoginSuccessResponse> login(@RequestBody @NotNull AuthDTO.LoginRequest loginRequest) {
         // Set the authentication using the provided details
@@ -47,7 +57,7 @@ public AuthController(
         SecurityContextHolder.getContext().setAuthentication(authentication);
 
         // Fetch the user record from the database
-        final var userEntity = userRepository.findByUsername(loginRequest.username()).orElseThrow(() -> new EntityNotFoundException("No userEntity with username " + loginRequest.username() + " found"));
+        final var userEntity = userRepository.findUserByUsername(loginRequest.username()).orElseThrow(() -> new EntityNotFoundException("No userEntity with username " + loginRequest.username() + " found"));
 
         // Generate the access and refresh tokens for the user
         final String accessToken = tokenService.generateAccessToken(userEntity);
@@ -59,10 +69,13 @@ public AuthController(
         return ResponseEntity.ok(response);
     }
 
-    // === Refresh token endpoint ===
+    /// The token refresh endpoint. Validates refresh tokens and returns new access tokens.
+    ///
+    /// @param refreshTokenRequest the [AuthDTO.RefreshTokenRequest] request body
+    /// @return a [ResponseEntity] containing a [AuthDTO.RefreshTokenResponse]
     @PostMapping("/api/auth/refresh")
     public ResponseEntity<AuthDTO.@NonNull RefreshTokenResponse> getRefreshToken(@RequestBody @NotNull AuthDTO.RefreshTokenRequest refreshTokenRequest) {
-        final var targetUserEntity = userRepository.findByUsername(refreshTokenRequest.username()).orElseThrow(() -> new EntityNotFoundException("No user with username " + refreshTokenRequest.username() + " found"));
+        final var targetUserEntity = userRepository.findUserByUsername(refreshTokenRequest.username()).orElseThrow(() -> new EntityNotFoundException("No user with username " + refreshTokenRequest.username() + " found"));
 
         // Validate the existing refresh token
         final UserEntity userEntity = tokenService.validateRefreshToken(refreshTokenRequest.refreshToken(), targetUserEntity);

src/main/java/org/openpodcastapi/opa/controllers/web/DocsController.java

@@ -4,17 +4,23 @@
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.GetMapping;
 
+/// Controller for the hosted documentation endpoints
 @Controller
 @Log4j2
 public class DocsController {
 
-    // === Docs index page ===
+    /// The hosted documentation endpoint. Redirects users to the index page.
+    ///
+    /// @return a redirect to the documentation
     @GetMapping("/docs")
     public String docs() {
         return "forward:/docs/index.html";
     }
 
-    // === Docs page with trailing slash ===
+    /// The hosted documentation endpoint (with a trailing slash).
+    /// Redirects users to the index page.
+    ///
+    /// @return a redirect to the documentation
     @GetMapping("/docs/")
     public String docsWithSlash() {
         return "forward:/docs/index.html";