📝 Add docstrings to feature/mosu-216

src/main/java/life/mosu/mosuserver/application/oauth/OAuthUserInfo.java

@@ -20,6 +20,14 @@ public record OAuthUserInfo(
         LocalDate birthDay
 ) {
 
+    /**
+     * Creates an {@code OAuthUserInfo} instance from the given OAuth provider and attribute map.
+     *
+     * @param oAuthProvider the OAuth provider to use for parsing user information
+     * @param attributes the raw attribute map returned by the OAuth provider
+     * @return an {@code OAuthUserInfo} object populated with user data
+     * @throws CustomRuntimeException if the OAuth provider is not supported
+     */
     public static OAuthUserInfo of(
             final OAuthProvider oAuthProvider,
             final Map<String, Object> attributes
@@ -30,6 +38,16 @@ public static OAuthUserInfo of(
         };
     }
 
+    /**
+     * Extracts and validates user information from Kakao OAuth attributes to create an {@code OAuthUserInfo} instance.
+     *
+     * Retrieves required fields such as name, email, phone number, gender, and birthday from the provided attributes map.
+     * If any essential information is missing or the birth date cannot be parsed, throws a {@code CustomRuntimeException}
+     * with the {@code INSUFFICIENT_KAKAO_USER_DATA} error code.
+     *
+     * @param attributes the attribute map returned from Kakao OAuth containing user information
+     * @return an {@code OAuthUserInfo} instance populated with the extracted user data
+     */
     private static OAuthUserInfo ofKakao(final Map<String, Object> attributes) {
         Map<String, Object> account = Optional.ofNullable(
                         (Map<String, Object>) attributes.get("kakao_account"))

src/main/java/life/mosu/mosuserver/application/oauth/OAuthUserService.java

@@ -24,6 +24,14 @@ public class OAuthUserService extends DefaultOAuth2UserService {
     private final UserJpaRepository userRepository;
     private final ProfileJpaRepository profileRepository;
 
+    /**
+     * Loads an OAuth2 user from the external provider, synchronizes user information with the application's database,
+     * and returns an OAuth2User representation including profile registration status.
+     *
+     * @param userRequest the OAuth2 user request containing provider and client details
+     * @return an OAuth2User object representing the authenticated user and their profile registration status
+     * @throws OAuth2AuthenticationException if user authentication fails with the external provider
+     */
     @Override
     public OAuth2User loadUser(final OAuth2UserRequest userRequest)
             throws OAuth2AuthenticationException {

src/main/java/life/mosu/mosuserver/global/filter/KmcTokenProcessingFilter.java

@@ -20,6 +20,17 @@ public class KmcTokenProcessingFilter extends OncePerRequestFilter {
 
     private final TokenService tokenService;
 
+    /**
+     * Processes requests matching a specific URI prefix by extracting a KMC token, retrieving the associated phone number, and setting authentication in the security context.
+     *
+     * Requests whose URI does not start with the configured prefix are passed through without processing. For matching requests, the filter extracts the "kmcToken" attribute, obtains the corresponding phone number via the token service, creates an authentication token, and sets it in the Spring Security context before continuing the filter chain.
+     *
+     * @param request the HTTP request
+     * @param response the HTTP response
+     * @param filterChain the filter chain to continue processing
+     * @throws ServletException if an error occurs during filtering
+     * @throws IOException if an I/O error occurs during filtering
+     */
     @Override
     protected void doFilterInternal(
             HttpServletRequest request,

src/main/java/life/mosu/mosuserver/global/handler/OAuth2LoginSuccessHandler.java

@@ -31,6 +31,15 @@ public class OAuth2LoginSuccessHandler implements AuthenticationSuccessHandler {
     private final AuthTokenManager authTokenManager;
     private final ObjectMapper objectMapper;
 
+    /**
+     * Handles successful OAuth2 authentication by generating authentication tokens, setting them as cookies,
+     * and redirecting the user to the specified URL with encoded login response data.
+     *
+     * @param request the HTTP request containing authentication and state parameters
+     * @param response the HTTP response to which cookies and redirect are added
+     * @param authentication the authentication object containing the authenticated user's details
+     * @throws IOException if an input or output exception occurs during response handling
+     */
     @Override
     public void onAuthenticationSuccess(
             final HttpServletRequest request,