code quality improvements

Author: az108

src/main/java/de/tum/cit/aet/analysis/service/EmailMappingService.java

@@ -49,6 +49,12 @@ public class EmailMappingService {
     //  Email mapping operations
     // ================================================================
 
+    /**
+     * Returns all email mappings for the given exercise.
+     *
+     * @param exerciseId the exercise ID
+     * @return list of email mapping DTOs
+     */
     public List<EmailMappingDTO> getAllMappings(Long exerciseId) {
         return emailMappingRepository.findAllByExerciseId(exerciseId)
                 .stream()
@@ -58,6 +64,17 @@ public List<EmailMappingDTO> getAllMappings(Long exerciseId) {
                 .toList();
     }
 
+    /**
+     * Creates a new email-to-student mapping. Resolves the student ID by name,
+     * re-assigns matching orphan chunks to the student, updates commit/line stats,
+     * and recalculates the CQI.
+     *
+     * @param exerciseId the exercise ID
+     * @param request    the mapping request with git email, student info and participation ID
+     * @return updated client response DTO
+     * @throws IllegalArgumentException      if participation not found or student ID is invalid
+     * @throws EmailMappingConflictException  if a mapping for the email already exists
+     */
     @Transactional
     public ClientResponseDTO createMapping(Long exerciseId, CreateEmailMappingRequestDTO request) {
         // 1. Find the team participation
@@ -117,6 +134,16 @@ public ClientResponseDTO createMapping(Long exerciseId, CreateEmailMappingReques
         return buildResponse(participation);
     }
 
+    /**
+     * Dismisses an orphan email without assigning it to a student.
+     * Chunks are NOT mutated; the dismissed mapping is used by clients
+     * to filter them into a separate section.
+     *
+     * @param exerciseId the exercise ID
+     * @param request    the dismiss request with git email and participation ID
+     * @return updated client response, or empty if participation not found
+     * @throws EmailMappingConflictException if a mapping for the email already exists
+     */
     @Transactional
     public Optional<ClientResponseDTO> dismissEmail(Long exerciseId, DismissEmailRequestDTO request) {
         // 1. Normalize and check for duplicates
@@ -143,6 +170,15 @@ public Optional<ClientResponseDTO> dismissEmail(Long exerciseId, DismissEmailReq
         return Optional.empty();
     }
 
+    /**
+     * Deletes an email mapping and reverts affected chunks back to external/orphan status.
+     * Subtracts the chunk stats from the previously assigned student and recalculates CQI.
+     *
+     * @param exerciseId the exercise ID
+     * @param mappingId  the mapping ID to delete
+     * @return updated client response for the last affected team, or empty if no chunks changed
+     * @throws IllegalArgumentException if mapping not found or does not belong to the exercise
+     */
     @Transactional
     public Optional<ClientResponseDTO> deleteMapping(Long exerciseId, UUID mappingId) {
         ExerciseEmailMapping mapping = emailMappingRepository.findById(mappingId)
@@ -196,13 +232,28 @@ public Optional<ClientResponseDTO> deleteMapping(Long exerciseId, UUID mappingId
     //  Template author operations
     // ================================================================
 
+    /**
+     * Returns all configured template authors for the given exercise.
+     *
+     * @param exerciseId the exercise ID
+     * @return list of template author DTOs
+     */
     public List<TemplateAuthorDTO> getTemplateAuthors(Long exerciseId) {
         return templateAuthorRepository.findByExerciseId(exerciseId)
                 .stream()
                 .map(ta -> new TemplateAuthorDTO(ta.getTemplateEmail(), ta.getAutoDetected()))
                 .toList();
     }
 
+    /**
+     * Replaces all template authors for an exercise. Chunks from removed template emails
+     * become regular orphans if not known via students or mappings. Chunks matching new
+     * template emails are marked as external. CQI is recalculated for all teams.
+     *
+     * @param exerciseId the exercise ID
+     * @param request    list of template author DTOs with emails
+     * @return list of updated client response DTOs for all teams
+     */
     @Transactional
     public List<ClientResponseDTO> setTemplateAuthors(Long exerciseId, List<TemplateAuthorDTO> request) {
         // Collect old emails
@@ -261,6 +312,14 @@ public List<ClientResponseDTO> setTemplateAuthors(Long exerciseId, List<Template
         return responses;
     }
 
+    /**
+     * Removes all template author configurations for an exercise.
+     * Chunks from old template authors that match a known student or mapping
+     * are unmarked as external. CQI is recalculated for all teams.
+     *
+     * @param exerciseId the exercise ID
+     * @return list of updated client response DTOs, or empty if none were configured
+     */
     @Transactional
     public Optional<List<ClientResponseDTO>> deleteTemplateAuthors(Long exerciseId) {
         List<ExerciseTemplateAuthor> existing = templateAuthorRepository.findByExerciseId(exerciseId);

src/main/java/de/tum/cit/aet/analysis/web/EmailMappingResource.java

@@ -30,12 +30,25 @@ public class EmailMappingResource {
     //  Email mapping endpoints
     // ================================================================
 
+    /**
+     * Returns all email mappings for the given exercise.
+     *
+     * @param exerciseId the exercise ID
+     * @return list of email mapping DTOs
+     */
     @GetMapping
     public ResponseEntity<List<EmailMappingDTO>> getAllMappings(@PathVariable Long exerciseId) {
         log.info("GET getAllMappings for exerciseId={}", exerciseId);
         return ResponseEntity.ok(emailMappingService.getAllMappings(exerciseId));
     }
 
+    /**
+     * Creates a new email mapping and recalculates CQI for the affected team.
+     *
+     * @param exerciseId the exercise ID
+     * @param request    the mapping request with git email, student info and participation ID
+     * @return updated client response DTO, 409 if mapping already exists, or 400 if invalid
+     */
     @PostMapping
     public ResponseEntity<ClientResponseDTO> createMapping(
             @PathVariable Long exerciseId,
@@ -51,6 +64,13 @@ public ResponseEntity<ClientResponseDTO> createMapping(
         }
     }
 
+    /**
+     * Dismisses an orphan email without assigning it to a student.
+     *
+     * @param exerciseId the exercise ID
+     * @param request    the dismiss request with git email and participation ID
+     * @return updated client response DTO, 409 if already mapped, or 204 if no participation found
+     */
     @PostMapping("/dismiss")
     public ResponseEntity<ClientResponseDTO> dismissEmail(
             @PathVariable Long exerciseId,
@@ -65,6 +85,13 @@ public ResponseEntity<ClientResponseDTO> dismissEmail(
         }
     }
 
+    /**
+     * Deletes an email mapping and recalculates CQI for affected teams.
+     *
+     * @param exerciseId the exercise ID
+     * @param mappingId  the mapping ID to delete
+     * @return updated client response DTO, or 204 if no chunks were affected
+     */
     @DeleteMapping("/{mappingId}")
     public ResponseEntity<ClientResponseDTO> deleteMapping(
             @PathVariable Long exerciseId,
@@ -88,12 +115,25 @@ public record TemplateAuthorDTO(
             Boolean autoDetected) {
     }
 
+    /**
+     * Returns all configured template authors for the given exercise.
+     *
+     * @param exerciseId the exercise ID
+     * @return list of template author DTOs
+     */
     @GetMapping("/template-author")
     public ResponseEntity<List<TemplateAuthorDTO>> getTemplateAuthors(@PathVariable Long exerciseId) {
         log.info("GET getTemplateAuthors for exerciseId={}", exerciseId);
         return ResponseEntity.ok(emailMappingService.getTemplateAuthors(exerciseId));
     }
 
+    /**
+     * Sets or replaces all template authors for an exercise and recalculates CQI.
+     *
+     * @param exerciseId the exercise ID
+     * @param request    list of template author DTOs with emails
+     * @return list of updated client response DTOs for all teams
+     */
     @PutMapping("/template-author")
     public ResponseEntity<List<ClientResponseDTO>> setTemplateAuthors(
             @PathVariable Long exerciseId,
@@ -102,6 +142,12 @@ public ResponseEntity<List<ClientResponseDTO>> setTemplateAuthors(
         return ResponseEntity.ok(emailMappingService.setTemplateAuthors(exerciseId, request));
     }
 
+    /**
+     * Removes all template author configurations for an exercise and recalculates CQI.
+     *
+     * @param exerciseId the exercise ID
+     * @return list of updated client response DTOs, or 204 if none configured
+     */
     @DeleteMapping("/template-author")
     public ResponseEntity<List<ClientResponseDTO>> deleteTemplateAuthors(
             @PathVariable Long exerciseId) {