docs(backend): Simplify controller docstrings

Author: dialvarezs

app_api/app/api/accounts/auth/controllers.py

@@ -1,9 +1,4 @@
-"""
-Authentication controller module.
-
-This module provides authentication endpoints for user login and logout
-functionality with JWT token-based authentication.
-"""
+"""Authentication controller module."""
 
 from typing import Annotated, Any
 
@@ -45,17 +40,6 @@ async def login(
 
         Validates user credentials, updates last login timestamp, and returns
         a JWT token for authenticated access.
-
-        Args:
-            request: The incoming request containing application state
-            data: Login credentials containing username and password
-            auth_service: Authentication service for credential validation
-
-        Returns:
-            Response containing JWT token and user information
-
-        Raises:
-            HTTPException: If credentials are invalid (401)
         """
         user = await auth_service.authenticate_user(data.username, data.password)
         if not user:
@@ -71,12 +55,7 @@ async def login(
     @post("/logout")
     async def logout(self) -> Response[None]:
         """
-        Log out the current user.
-
-        Clears the authentication token cookie to log out the user.
-
-        Returns:
-            Empty response with token cookie deleted
+        Log out the current user by clearing the authentication token.
         """
         response = Response(content=None, status_code=HTTP_200_OK)
         response.delete_cookie("token")

app_api/app/api/accounts/permissions/controllers.py

@@ -30,15 +30,16 @@ class PermissionController(Controller):
     dependencies = {"permission_service": Provide(provide_permission_service)}
     exception_handlers = {NotFoundError: not_found_error_handler}
 
-    @get("/", summary="ListPermissions", guards=[has_permission("permissions", "list")])
+    @get(
+        "/",
+        summary="ListPermissions",
+        guards=[has_permission("permissions", "list")],
+    )
     async def list(self, permission_service: PermissionService) -> Sequence[Permission]:
         """
-        List all permissions sorted by name.
-
-        Requires the 'permissions:list' permission.
+        List all permissions in the system.
 
-        Raises:
-            PermissionDeniedException: If the user lacks 'permissions:list' permission
+        This endpoint requires the 'permissions:list' permission.
         """
         return await permission_service.list()
 
@@ -52,23 +53,21 @@ async def create(self, data: Permission, permission_service: PermissionService)
         """
         Create a new permission.
 
+        Creates a new permission with the provided resource and action data.
         Requires the 'permissions:create' permission.
-
-        Raises:
-            PermissionDeniedException: If the user lacks 'permissions:create' permission
         """
         return await permission_service.create(data)
 
-    @get("/{permission_id:uuid}", summary="FetchPermission", guards=[has_permission("permissions", "read")])
+    @get(
+        "/{permission_id:uuid}",
+        summary="FetchPermission",
+        guards=[has_permission("permissions", "read")],
+    )
     async def fetch(self, permission_id: UUID, permission_service: PermissionService) -> Permission:
         """
-        Fetch a specific permission by ID.
+        Fetch a specific permission by its UUID.
 
         Requires the 'permissions:read' permission.
-
-        Raises:
-            NotFoundError: If the permission is not found (handled by not_found_error_handler)
-            PermissionDeniedException: If the user lacks 'permissions:read' permission
         """
         return await permission_service.get(permission_id)
 
@@ -85,13 +84,9 @@ async def update(
         permission_service: PermissionService,
     ) -> Permission:
         """
-        Update an existing permission.
+        Update an existing permission's data.
 
         Requires the 'permissions:update' permission.
-
-        Raises:
-            NotFoundError: If the permission is not found (handled by not_found_error_handler)
-            PermissionDeniedException: If the user lacks 'permissions:update' permission
         """
         return await permission_service.update(item_id=permission_id, data=data.as_builtins())
 
@@ -103,12 +98,8 @@ async def update(
     )
     async def delete(self, permission_id: UUID, permission_service: PermissionService) -> None:
         """
-        Delete a permission by ID.
+        Delete a permission from the system.
 
         Requires the 'permissions:delete' permission.
-
-        Raises:
-            NotFoundError: If the permission is not found (handled by not_found_error_handler)
-            PermissionDeniedException: If the user lacks 'permissions:delete' permission
         """
         await permission_service.delete(permission_id)

app_api/app/api/accounts/roles/controllers.py

@@ -1,9 +1,4 @@
-"""
-Role management controller module.
-
-This module provides CRUD operations for managing user roles
-in the role-based access control system.
-"""
+"""Role management controller module."""
 
 from typing import Any, Sequence
 from uuid import UUID
@@ -40,88 +35,62 @@ class RoleController(Controller):
     dependencies = {"role_service": Provide(provide_role_service)}
     exception_handlers = {NotFoundError: not_found_error_handler}
 
-    @get("/", summary="ListRoles", guards=[has_permission("roles", "list")])
+    @get(
+        "/",
+        summary="ListRoles",
+        guards=[has_permission("roles", "list")],
+    )
     async def list(self, role_service: RoleService) -> Sequence[Role]:
         """
-        Get all roles in the system.
-
-        Requires the 'roles:list' permission.
-
-        Args:
-            role_service: Role service for business operations
+        List all roles in the system.
 
-        Returns:
-            List of all role objects
-
-        Raises:
-            PermissionDeniedException: If the user lacks 'roles:list' permission
+        This endpoint requires the 'roles:list' permission.
         """
         return await role_service.list()
 
-    @post("/", summary="CreateRole", dto=RoleCreateDTO, guards=[has_permission("roles", "create")])
+    @post(
+        "/",
+        summary="CreateRole",
+        dto=RoleCreateDTO,
+        guards=[has_permission("roles", "create")],
+    )
     async def create(self, data: Role, role_service: RoleService) -> Role:
         """
-        Create a new role.
-
-        Requires the 'roles:create' permission.
-
-        Args:
-            data: Role data for creation
-            role_service: Role service for business operations
+        Create a new role with associated permissions.
 
-        Returns:
-            The created role object
-
-        Raises:
-            PermissionDeniedException: If the user lacks 'roles:create' permission
-            HTTPException: If validation fails
+        Creates a new role with the provided data and assigns any specified
+        permissions. Requires the 'roles:create' permission.
         """
         try:
             return await role_service.create_role_with_permissions(data)
         except ValueError as exc:
             raise HTTPException(detail=str(exc), status_code=400) from exc
 
-    @get("/{role_id:uuid}", summary="FetchRole", guards=[has_permission("roles", "read")])
+    @get(
+        "/{role_id:uuid}",
+        summary="FetchRole",
+        guards=[has_permission("roles", "read")],
+    )
     async def fetch(self, role_id: UUID, role_service: RoleService) -> Role:
         """
-        Get a specific role by ID.
+        Fetch a specific role by its UUID.
 
         Requires the 'roles:read' permission.
-
-        Args:
-            role_id: UUID of the role to retrieve
-            role_service: Role service for business operations
-
-        Returns:
-            The requested role object
-
-        Raises:
-            NotFoundError: If the role is not found (handled by not_found_error_handler)
-            PermissionDeniedException: If the user lacks 'roles:read' permission
         """
         return await role_service.get(role_id)
 
     @patch(
-        "/{role_id:uuid}", summary="UpdateRole", dto=RoleUpdateDTO, guards=[has_permission("roles", "update")]
+        "/{role_id:uuid}",
+        summary="UpdateRole",
+        dto=RoleUpdateDTO,
+        guards=[has_permission("roles", "update")],
     )
     async def update(self, role_id: UUID, data: DTOData[Role], role_service: RoleService) -> Role:
         """
-        Update an existing role.
-
-        Requires the 'roles:update' permission.
-
-        Args:
-            role_id: UUID of the role to update
-            data: Updated role data
-            role_service: Role service for business operations
-
-        Returns:
-            The updated role object
+        Update an existing role's data and permissions.
 
-        Raises:
-            NotFoundError: If the role is not found (handled by not_found_error_handler)
-            PermissionDeniedException: If the user lacks 'roles:update' permission
-            HTTPException: If validation fails
+        Updates the specified role's information and permission assignments
+        with the provided data. Requires the 'roles:update' permission.
         """
         try:
             return await role_service.update_role_with_permissions(role_id, data.as_builtins())