AOSSIE-Org / AOSSIE-Org/PictoPy

DOC: Remove dead app/schemas/test.py and compress signature-restating docstrings (follow-up to #1458)

Đang mở
#1,499 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
documentation enhancement
Ngôn ngữ chính
Python
Star
284
Fork
680
Merge trung bình
7 ngày 5 giờ
Pull request đã merge (30 ngày)
4

Mô tả

### What's wrong with the existing documentation

Two follow-ups from #1458 that #1480 deliberately left out of scope to keep that PR reviewable. Both are in-code documentation rather than prose docs.

**1. `backend/app/schemas/test.py` is dead, and provably so once #1480 merges.**

51 lines of Pydantic models. On `main` today its only reference anywhere in the repository is a commented-out import:

```
backend/app/routes/test.py:9:# from app.schemas.test import (
```

#1480 deletes `routes/test.py` outright (it was 173 lines, entirely commented out). After that merges, `schemas/test.py` has zero references of any kind, commented or live. It should go the same way. Git remembers it.

This is blocked on #1480 and should not be attempted before it lands.

**2. Multi-line docstrings that restate the signature.**

`AGENTS.md` says comments should be "one or two lines, explaining *why* rather than *what*" and that "the codebase does not use long prose comment blocks or multi-paragraph docstrings". Measured against `main` (`510d4d0`) with an AST walk over all 123 backend Python files:

| | count |
| --- | --- |
| multi-line docstrings | 369 |
| Google-style `Args:` / `Returns:` / `Raises:` blocks | 73 |

Heaviest files:

```
20 backend/app/database/memories.py
15 backend/app/utils/face_clusters.py
15 backend/app/utils/memory_curator.py
14 backend/app/database/folders.py
14 backend/app/utils/videos.py
14 backend/tests/test_memory_curator.py
13 backend/app/utils/memory_scoring.py
13 backend/tests/test_memory_signals_db.py
```

These numbers have grown since I first scoped this in #1480's body, which is an argument for doing it rather than leaving it.

The same rule from #1458 applies: this is not a blanket strip. Per @rohan-pandeyy's steer on that issue, docstrings carrying real reasoning get compressed with the argument intact, and only the ones restating the signature below them get removed. An `Args:` block that names each parameter and its type, when the annotated signature already says both, is the clear case.

Suggested split, since 369 sites is too much for one reviewable PR:

- the dead file on its own, straight after #1480 merges
- `app/database/` and `app/utils/` in one pass
- `tests/` in a second

### Add ScreenShots

Not applicable, this is in-code documentation.

### Record

- [x] I agree to follow this project's Code of Conduct
- [x] I want to work on this issue

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

First verify that #1480 has merged, then read AGENTS.md and inspect backend/app/schemas/test.py plus the app/database/ and app/utils/ docstrings listed in the issue. Remove the dead file and compress only signature-restating docstrings, preserving reasoning; leave the tests/ pass for a separate reviewable change.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python
Lĩnh vực
backend, documentation
Loại issue
Tài liệu
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
62/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.