docs: 세모피드 메서드 주석 추가

Author: pooreumjung

src/main/java/com/semosan/api/domain/semofeed/controller/SemoFeedController.java

@@ -40,38 +40,37 @@ public ResponseEntity<ApiResponse<SemoFeedResponse>> create(
 
     @GetMapping
     @Override
+    // 공개 세모피드 목록을 작성자 정보와 이모지 상태까지 포함해 조회합니다.
     public ResponseEntity<ApiResponse<PageResponse<SemoFeedResponse>>> listPublic(
             @AuthenticationPrincipal Long userId,
             @PageableDefault(size = 100) Pageable pageable
     ) {
         if (pageable.getPageSize() > 100) {
             pageable = PageRequest.of(pageable.getPageNumber(), 100, pageable.getSort());
         }
-        return ApiResponse.success(
-                SuccessStatus.SEMOFEED_LIST_SUCCESS,
-                PageResponse.from(semoFeedService.listPublic(pageable, userId))
-        );
+        PageResponse<SemoFeedResponse> response = PageResponse.from(semoFeedService.listPublic(pageable, userId));
+        return ApiResponse.success(SuccessStatus.SEMOFEED_LIST_SUCCESS, response);
     }
 
     @PostMapping("/{semoFeedId}/emojis")
     @Override
+    // 세모피드 이모지를 타입별로 등록하거나 취소합니다.
     public ResponseEntity<ApiResponse<SemoFeedEmojiToggleResponse>> toggleEmoji(
             @AuthenticationPrincipal Long userId,
             @PathVariable Long semoFeedId,
             @Valid @RequestBody SemoFeedEmojiRequest request
     ) {
-        return ApiResponse.success(
-                SuccessStatus.SEMOFEED_EMOJI_TOGGLE_SUCCESS,
-                semoFeedEmojiService.toggleWithCount(userId, semoFeedId, request.emojiType())
-        );
+        SemoFeedEmojiToggleResponse response = semoFeedEmojiService.toggleWithCount(userId, semoFeedId, request.emojiType());
+        return ApiResponse.success(SuccessStatus.SEMOFEED_EMOJI_TOGGLE_SUCCESS, response);
     }
 
     @GetMapping("/me")
     @Override
     public ResponseEntity<ApiResponse<List<SemoFeedResponse>>> listMine(
             @AuthenticationPrincipal Long userId
     ) {
-        return ApiResponse.success(SuccessStatus.SEMOFEED_MY_LIST_SUCCESS, semoFeedService.listMine(userId));
+        List<SemoFeedResponse> response = semoFeedService.listMine(userId);
+        return ApiResponse.success(SuccessStatus.SEMOFEED_MY_LIST_SUCCESS, response);
     }
 
     @PatchMapping("/{semoFeedId}/public")

src/main/java/com/semosan/api/domain/semofeed/dto/SemoFeedResponse.java

@@ -45,6 +45,7 @@ public static SemoFeedResponse of(
         );
     }
 
+    // 새로 생성된 세모피드 응답에 기본 이모지 개수를 채웁니다.
     private static Map<SemoFeedEmojiType, Long> defaultEmojiCounts() {
         Map<SemoFeedEmojiType, Long> emojiCounts = new EnumMap<>(SemoFeedEmojiType.class);
         for (SemoFeedEmojiType emojiType : SemoFeedEmojiType.values()) {
@@ -53,6 +54,7 @@ private static Map<SemoFeedEmojiType, Long> defaultEmojiCounts() {
         return emojiCounts;
     }
 
+    // 새로 생성된 세모피드 응답에 기본 내 반응 상태를 채웁니다.
     private static Map<SemoFeedEmojiType, Boolean> defaultReactedByMe() {
         Map<SemoFeedEmojiType, Boolean> reactedByMe = new EnumMap<>(SemoFeedEmojiType.class);
         for (SemoFeedEmojiType emojiType : SemoFeedEmojiType.values()) {

src/main/java/com/semosan/api/domain/semofeed/service/SemoFeedEmojiService.java

@@ -29,6 +29,7 @@ public class SemoFeedEmojiService {
     private final UserRepository userRepository;
 
     @Transactional(noRollbackFor = DataIntegrityViolationException.class)
+    // 이모지 반응을 토글하고 변경 후 해당 타입의 개수를 반환합니다.
     public SemoFeedEmojiToggleResponse toggleWithCount(
             Long userId,
             Long semoFeedId,
@@ -43,6 +44,7 @@ public SemoFeedEmojiToggleResponse toggleWithCount(
         return new SemoFeedEmojiToggleResponse(emojiType, reacted, count);
     }
 
+    // 기존 반응이 있으면 취소하고, 없으면 새 반응을 저장합니다.
     private boolean toggle(SemoFeed semoFeed, User user, SemoFeedEmojiType emojiType) {
         Optional<SemoFeedEmoji> existing = semoFeedEmojiRepository.findBySemoFeedAndUserAndEmojiType(
                 semoFeed,
@@ -69,11 +71,13 @@ private boolean toggle(SemoFeed semoFeed, User user, SemoFeedEmojiType emojiType
         }
     }
 
+    // 세모피드가 없으면 도메인 예외를 던집니다.
     private SemoFeed findSemoFeedOrThrow(Long semoFeedId) {
         return semoFeedRepository.findById(semoFeedId)
                 .orElseThrow(() -> new GeneralException(ErrorStatus.SEMOFEED_NOT_FOUND));
     }
 
+    // 사용자가 없으면 도메인 예외를 던집니다.
     private User findUserOrThrow(Long userId) {
         return userRepository.findById(userId)
                 .orElseThrow(() -> new GeneralException(ErrorStatus.USER_NOT_FOUND));

src/main/java/com/semosan/api/domain/semofeed/service/SemoFeedService.java

@@ -46,6 +46,7 @@ public List<SemoFeedResponse> listMine(Long userId) {
                 .toList();
     }
 
+    // 공개 세모피드 목록을 N+1 없이 응답 DTO로 조립합니다.
     public Page<SemoFeedResponse> listPublic(Pageable pageable, Long userId) {
         Page<SemoFeed> semoFeeds = semoFeedRepository.findPublic(pageable);
         return toResponsePage(semoFeeds, userId);
@@ -73,11 +74,13 @@ private SemoFeed findOwned(Long userId, Long semoFeedId) {
         return semoFeed;
     }
 
+    // 페이지 메타데이터를 유지하면서 각 세모피드를 응답 DTO로 변환합니다.
     private Page<SemoFeedResponse> toResponsePage(Page<SemoFeed> semoFeeds, Long userId) {
         SemoFeedResponseAssembler assembler = createResponseAssembler(semoFeeds.getContent(), userId);
         return semoFeeds.map(assembler::toResponse);
     }
 
+    // 피드별 이모지 집계와 내 반응 정보를 한 번씩 조회해 조립기를 만듭니다.
     private SemoFeedResponseAssembler createResponseAssembler(List<SemoFeed> semoFeeds, Long userId) {
         List<Long> semoFeedIds = semoFeeds.stream()
                 .map(SemoFeed::getId)
@@ -89,6 +92,7 @@ private SemoFeedResponseAssembler createResponseAssembler(List<SemoFeed> semoFee
         return new SemoFeedResponseAssembler(userId, emojiCounts, reactedTypes);
     }
 
+    // 피드 ID 목록 기준으로 이모지 타입별 개수를 한 번에 조회합니다.
     private Map<Long, Map<SemoFeedEmojiType, Long>> findEmojiCounts(List<Long> semoFeedIds) {
         if (semoFeedIds.isEmpty()) {
             return Map.of();
@@ -104,6 +108,7 @@ private Map<Long, Map<SemoFeedEmojiType, Long>> findEmojiCounts(List<Long> semoF
                 ));
     }
 
+    // 피드 ID 목록 기준으로 로그인 사용자가 누른 이모지 타입을 한 번에 조회합니다.
     private Map<Long, Set<SemoFeedEmojiType>> findReactedTypes(List<Long> semoFeedIds, Long userId) {
         if (semoFeedIds.isEmpty() || userId == null) {
             return Map.of();
@@ -122,6 +127,7 @@ private record SemoFeedResponseAssembler(
             Map<Long, Set<SemoFeedEmojiType>> reactedTypes
     ) {
 
+        // 세모피드 엔티티와 집계 결과를 최종 응답 DTO로 변환합니다.
         private SemoFeedResponse toResponse(SemoFeed semoFeed) {
             return SemoFeedResponse.of(
                     semoFeed,
@@ -131,6 +137,7 @@ private SemoFeedResponse toResponse(SemoFeed semoFeed) {
             );
         }
 
+        // 누락된 이모지 타입도 0으로 채워 응답 계약을 일정하게 유지합니다.
         private Map<SemoFeedEmojiType, Long> completeEmojiCounts(Map<SemoFeedEmojiType, Long> counts) {
             Map<SemoFeedEmojiType, Long> completeCounts = new EnumMap<>(SemoFeedEmojiType.class);
             for (SemoFeedEmojiType emojiType : SemoFeedEmojiType.values()) {
@@ -139,6 +146,7 @@ private Map<SemoFeedEmojiType, Long> completeEmojiCounts(Map<SemoFeedEmojiType,
             return completeCounts;
         }
 
+        // 누락된 이모지 타입도 false로 채워 응답 계약을 일정하게 유지합니다.
         private Map<SemoFeedEmojiType, Boolean> completeReactedByMe(Set<SemoFeedEmojiType> reactedTypes) {
             Map<SemoFeedEmojiType, Boolean> completeReactedTypes = new EnumMap<>(SemoFeedEmojiType.class);
             for (SemoFeedEmojiType emojiType : SemoFeedEmojiType.values()) {