studentService注释添加

src/main/java/com/codesdream/ase/model/student/Student.java

@@ -1,11 +1,11 @@
 package com.codesdream.ase.model.student;
 
-import com.codesdream.ase.model.mark.Tag;
 import com.codesdream.ase.model.permission.User;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
-import javax.persistence.*;
+import javax.persistence.ElementCollection;
+import javax.persistence.Entity;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -18,6 +18,7 @@ public class Student extends User {
 
     Boolean isShowGrade = true;
 
+    // 请务必确保此属性的初始化 @Todo
     @ElementCollection
     Map<String, Boolean> privacy = new HashMap<String, Boolean>(){{
         put("score", true);

src/main/java/com/codesdream/ase/service/student/StudentService.java

@@ -37,6 +37,13 @@ public class StudentService {
     @Resource
     HonorRepository honorRepository;
 
+    /**
+     * 用于创建一个公告
+     * @param title 公告标题
+     * @param description 公告内容
+     * @param files 公告所需附件
+     * @return 已经持久化的公告
+     */
     public Notification createNotification(String title, String description, List<File> files){
         Notification notification = new Notification();
 
@@ -47,6 +54,11 @@ public class StudentService {
         return notificationRepository.save(notification);
     }
 
+    /**
+     * 在数据库中删除指定公告
+     * @param notificationId 需要删除的公告id，如果此id不存在，则会抛出异常，删除失败
+     * @return 是否删除成功
+     */
     public boolean cancelNotification(int notificationId){
         Optional<Notification> notification = notificationRepository.findById(notificationId);
         if(notification.isPresent()){
@@ -58,10 +70,25 @@ public class StudentService {
         }
     }
 
+    /**
+     * 指定学生加入指定活动
+     * @see ActivityService#addMember(int, int, boolean)
+     * @param studentId 加入的学生的id
+     * @param activityId 加入的学生的活动
+     * @return 加入学生后、持久化了的活动
+     */
     public Activity attendActivity(int studentId, int activityId){
         return activityService.addMember(activityId, studentId, true);
     }
 
+    /**
+     * 创建并持久化一个荣誉
+     * @see Image
+     * @param studentId 荣誉所对应的学生id
+     * @param description 荣誉的描述
+     * @param images 荣誉的证明材料（图片）
+     * @return 持久化好的荣誉
+     */
     public Honor createHonor(int studentId, String description, List<Image> images){
 
         Honor honor = new Honor();
@@ -73,6 +100,13 @@ public class StudentService {
         return honorRepository.save(honor);
     }
 
+    /**
+     * 更新一个荣誉
+     * @param honorId 荣誉id
+     * @param description 荣誉描述，若为空则不做修改
+     * @param images 需要更新的附件，若为空则不做修改，否则会覆盖对应荣誉所有附件
+     * @return 更新后的荣誉，若id不存在则返回null
+     */
     public Honor updateHonor(int honorId, String description, List<Image> images){
 
         Optional<Honor> optionalHonor = honorRepository.findById(honorId);
@@ -89,6 +123,13 @@ public class StudentService {
         return honorRepository.save(honor);
     }
 
+    /**
+     * 更新指定学生的隐私政策
+     * @param studentId 学生id
+     * @param privacyList 一串字符，用以标明可公开的隐私有哪些，需要保证此字符序列被["score","attendance",
+     *                    "step","honor"]这一标准序列完全包含。序列有待更新@Todo
+     * @return 是否更新成功。若privacyList不符合规范则更新失败，若studentId无实体与之对应则更新失败
+     */
     public boolean updatePrivacy(int studentId, List<String> privacyList){
 
         Optional<Student> optionalStudent = studentRepository.findById(studentId);
@@ -106,10 +147,19 @@ public class StudentService {
             }
         }
         else {
-            throw new NotFoundException("No such privacy.");
+            throw new NotFoundException("No such student.");
         }
     }
 
+    /**
+     * 用于学生对个人信息的编辑
+     * @see GeneralValidator#isTelNumber(String)
+     * @param studentId 指定学生id
+     * @param telNum 电话，若为0，则表示无需更改；否则需要满足电话号码的合法性
+     * @param profilePic 头像，若为null，则表示无需更改
+     * @param email 电子邮箱，若为空，则表示无需修改
+     * @return 编辑好个人信息的学生
+     */
     public Student editProfile(int studentId, String telNum, Image profilePic, String email){
         Optional<Student> optionalStudent = studentRepository.findById(studentId);
         if(!optionalStudent.isPresent()){