fix documentation

rating_api/routes/comment.py

@@ -39,8 +39,15 @@
 @comment.post("", response_model=CommentGet)
 async def create_comment(lecturer_id: int, comment_info: CommentPost, user=Depends(UnionAuth())) -> CommentGet:
     """
+    Scopes: `["rating.comment.create"]`
+
     Создает комментарий к преподавателю в базе данных RatingAPI
-    Для создания комментария нужно быть авторизованным
+
+    Исключение **TooManyCommentsToLecturer**, если число комментариев превысило лимит
+
+    Исключение **CommentTooLong**, если комментарий слишком длинный
+
+    Исключение **ForbiddenSymbol**, если в комментарии использованы запрещенные символы
     """
     # Проверяем, что лектор с заданным id существует
     Lecturer.get(session=db.session, id=lecturer_id)
@@ -148,6 +155,7 @@ async def import_comments(
 ) -> CommentGetAll:
     """
     Scopes: `["rating.comment.import"]`
+
     Создает комментарии в базе данных RatingAPI
     """
     number_of_comments = len(comments_info.comments)
@@ -165,7 +173,11 @@ async def import_comments(
 @comment.get("/{uuid}", response_model=CommentGet)
 async def get_comment(uuid: UUID, user=Depends(UnionAuth(auto_error=False, allow_none=False))) -> CommentGet:
     """
+    Scopes: `["rating.comment.read"]`
+
     Возвращает комментарий по его UUID в базе данных RatingAPI
+
+    Исключение **ObjectNotFound**, если `uuid` не найден
     """
     comment: Comment = Comment.query(session=db.session).filter(Comment.uuid == uuid).one_or_none()
     if comment is None:
@@ -213,6 +225,10 @@ async def get_comments(
      `unreviewed` - вернет все непроверенные комментарии, если True. По дефолту False.
 
      `asc_order` -Если передано true, сортировать в порядке возрастания. Иначе - в порядке убывания
+
+     Исключение **ObjectNotFound**, если комментарий с введенными параметрами не найден
+
+     Исключение **ForbiddenAction**, если пользователь пытается получить непроверенный комментарий
     """
     comments_query = (
         Comment.query(session=db.session)
@@ -288,6 +304,8 @@ async def review_comment(
     `review_status` - возможные значения
     `approved` - комментарий одобрен и возвращается при запросе лектора
     `dismissed` - комментарий отклонен, не отображается в запросе лектора
+
+    Исключение **ObjectNotFound**, если `uuid` не найден
     """
     check_comment: Comment = Comment.query(session=db.session).filter(Comment.uuid == uuid).one_or_none()
 
@@ -301,7 +319,15 @@ async def review_comment(
 
 @comment.patch("/{uuid}", response_model=CommentGet)
 async def update_comment(uuid: UUID, comment_update: CommentUpdate, user=Depends(UnionAuth())) -> CommentGet:
-    """Позволяет изменить свой неанонимный комментарий"""
+    """
+    Scopes: `["rating.comment.update"]`
+
+    Позволяет изменить свой неанонимный комментарий
+
+    Исключение **ForbiddenAction** при попытке отредактировать чужой комментарий
+
+    Исключение **ForbiddenAction** при попытке отредактировать анонимный комментарий
+    """
     comment: Comment = Comment.get(session=db.session, id=uuid)  # Ошибка, если не найден
 
     if comment.user_id != user.get("id") or comment.user_id is None:
@@ -334,6 +360,10 @@ async def delete_comment(
     Scopes: `["rating.comment.delete"]`
 
     Удаляет комментарий по его UUID в базе данных RatingAPI
+
+    Исключение **ObjectNotFound**, если `uuid` не найден
+
+    Исключение **ForbiddenAction** при попытке удалить комментарий пользователем без прав
     """
     comment = Comment.get(uuid, session=db.session)
     if comment is None:
@@ -358,22 +388,11 @@ async def like_comment(
     user=Depends(UnionAuth()),
 ) -> CommentGet:
     """
-    Handles like/dislike reactions for a comment.
-
-    This endpoint allows authenticated users to react to a comment (like/dislike) or change their existing reaction.
-    If the user has no existing reaction, a new one is created. If the user changes their reaction, it gets updated.
-    If the user clicks the same reaction again, the reaction is removed.
-
-    Args:
-        uuid (UUID): The UUID of the comment to react to.
-        reaction (Reaction): The reaction type (like/dislike).
-        user (dict): Authenticated user data from UnionAuth dependency.
+    Scopes: `["rating.comment.write"]`
 
-    Returns:
-        CommentGet: The updated comment with reactions in CommentGet format.
+    Ставит лайк или дизлайк на комментарий по его uuid
 
-    Raises:
-        ObjectNotFound: If the comment with given UUID doesn't exist.
+    Исключение **ObjectNotFound**, если `uuid` не найден
     """
     comment = Comment.get(session=db.session, id=uuid)
     if not comment:

rating_api/routes/lecturer.py

@@ -35,6 +35,8 @@ async def create_lecturer(
     Scopes: `["rating.lecturer.create"]`
 
     Создает преподавателя в базе данных RatingAPI
+
+    Исключение **AlreadyExists**, если преподаватель с введеным `timetable_id` уже существует
     """
     get_lecturer: Lecturer = (
         Lecturer.query(session=db.session).filter(Lecturer.timetable_id == lecturer_info.timetable_id).one_or_none()
@@ -95,6 +97,8 @@ async def update_lecturer_rating(
 async def get_lecturer_by_timetable_id(timetable_id: int) -> LecturerGet:
     """
     Возвращает преподавателя по его timetable_id
+
+    Исключение **ObjectNotFound**, если `timetable_id` не найден
     """
     lecturer: Lecturer = Lecturer.query(session=db.session).filter(Lecturer.timetable_id == timetable_id).one_or_none()
     if lecturer is None:
@@ -112,6 +116,8 @@ async def get_lecturer(id: int, info: list[Literal["comments"]] = Query(default=
     *QUERY* `info: string` - возможные значения `'comments'`.
     Если передано `'comments'`, то возвращаются одобренные комментарии к преподавателю.
     Subject лектора возвращшается либо из базы данных, либо из любого аппрувнутого комментария
+
+    Исключение **ObjectNotFound**, если `id` не найден
     """
     lecturer: Lecturer = Lecturer.query(session=db.session).filter(Lecturer.id == id).one_or_none()
     if lecturer is None:
@@ -168,6 +174,8 @@ async def get_lecturers(
     `mark`
     Поле для оценки. Если передано, то возвращает только тех преподавателей, для которых средняя общая оценка ('general_mark')
     больше, чем переданный 'mark'.
+
+    Исключение **ObjectNotFound**, если преподаватель с введенными параметрами не найден
     """
     lecturers_query = lecturer_filter.filter(
         Lecturer.query(session=db.session).outerjoin(Lecturer.comments).group_by(Lecturer.id)
@@ -212,6 +220,10 @@ async def update_lecturer(
 ) -> LecturerGet:
     """
     Scopes: `["rating.lecturer.update"]`
+
+    Обновляет данные о преподавателе по его id
+
+    Исключение **ObjectNotFound**, если `id` не найден
     """
     lecturer = Lecturer.get(id, session=db.session)
     if lecturer is None:
@@ -238,6 +250,10 @@ async def delete_lecturer(
 ):
     """
     Scopes: `["rating.lecturer.delete"]`
+
+    Удаляет из базы данных преподавателя по его id
+
+    Исключение **ObjectNotFound**, если `id` не найден
     """
     check_lecturer = Lecturer.get(session=db.session, id=id)
     if check_lecturer is None: