[Documentation] API audit follow-through: close the gaps from docs/api-audit-2026-04.md #314

New issue

Open

opened 2026-04-17 03:26:00 +00:00 by john · 0 comments

john commented

2026-04-17 03:26:00 +00:00

Owner

Context

docs/api-audit-2026-04.md catalogs the full Python API surface (93 items: 46 exported types, 14 internal types, 10 enums, 13 module functions, 7 properties, 5 singletons). It identifies 15 findings grouped into breaking / non-breaking / future.

Several breaking findings have been closed:

#304 (F1, camelCase functions)
#305 (F11, sprite_number)
#306 (F13, legacy string enum comparisons)
#307 (F6, Color __eq__/__ne__)
#308 (F4, Grid.position alias)

The documentation side the audit was meant to unblock was not completed. This issue tracks closing that loop.

Work to do

1. Regenerate and compare

Run ./tools/generate_all_docs.sh and compare output against the 93-item catalog. For each item, verify:

The class appears in the generated HTML / MD / man / .pyi
The docstring is substantive (not a placeholder like "SFML Vector Object")
Property read/write flags match reality
Method signatures match the audit

2. Findings flagged in the audit

F14 Terse docstrings — Vector, Font, Texture, GridPoint, GridPointState had placeholder tp_doc. Commit 1dec6fa is titled "Improve terse docstrings on Vector, Font, Texture, GridPoint, GridPointState" — verify it actually covers all five and the generated docs look right.
F15 Missing MCRF_ macro usage* — identify types whose methods use raw docstrings instead of MCRF_METHOD(...). The macro system is how docs stay in sync with code.
F8 Font methods — Font has no methods at all (.family, .source only). Decide: is this acceptable for 1.0 or do we add basic text metrics?
F7 Music.pitch — Sound has pitch, Music doesn't. Trivial to add if desired.
F10 Animation direct construction deprecation warning — should Animation(...) emit a DeprecationWarning pointing users at .animate()?

3. Downstream artifacts

stubs/mcrfpy.pyi should reflect every item in the catalog with correct type annotations
docs/API_REFERENCE_DYNAMIC.md and docs/api_reference_dynamic.html should be regenerated
docs/mcrfpy.3 (man page) should be regenerated

4. Commit hygiene

One commit per meaningful batch. Reference this issue.

Not in scope

Writing new tutorial content (separate effort, see #167)
Changing external prose docs in docs/ beyond what the audit covers
3D / Experimental type documentation (exempt from 1.0 freeze)

Why now

Part of Track 1 (API Freeze) in the current ROADMAP.md. Settling the documentation surface is a precondition for the freeze itself — you can't commit to a stable API if the public-facing docs don't describe it accurately.

docs/api-audit-2026-04.md — source document
CLAUDE.md → "Documentation Macro System" — how MCRF_* macros work
tools/generate_all_docs.sh — the single-command regeneration path

## Context `docs/api-audit-2026-04.md` catalogs the full Python API surface (93 items: 46 exported types, 14 internal types, 10 enums, 13 module functions, 7 properties, 5 singletons). It identifies 15 findings grouped into breaking / non-breaking / future. Several breaking findings have been closed: - #304 (F1, camelCase functions) - #305 (F11, `sprite_number`) - #306 (F13, legacy string enum comparisons) - #307 (F6, Color `__eq__`/`__ne__`) - #308 (F4, `Grid.position` alias) The **documentation side** the audit was meant to unblock was not completed. This issue tracks closing that loop. ## Work to do ### 1. Regenerate and compare Run `./tools/generate_all_docs.sh` and compare output against the 93-item catalog. For each item, verify: - The class appears in the generated HTML / MD / man / .pyi - The docstring is substantive (not a placeholder like "SFML Vector Object") - Property read/write flags match reality - Method signatures match the audit ### 2. Findings flagged in the audit - **F14 Terse docstrings** — Vector, Font, Texture, GridPoint, GridPointState had placeholder `tp_doc`. Commit `1dec6fa` is titled "Improve terse docstrings on Vector, Font, Texture, GridPoint, GridPointState" — verify it actually covers all five and the generated docs look right. - **F15 Missing MCRF_* macro usage** — identify types whose methods use raw docstrings instead of `MCRF_METHOD(...)`. The macro system is how docs stay in sync with code. - **F8 Font methods** — Font has no methods at all (`.family`, `.source` only). Decide: is this acceptable for 1.0 or do we add basic text metrics? - **F7 Music.pitch** — Sound has pitch, Music doesn't. Trivial to add if desired. - **F10 Animation direct construction deprecation warning** — should `Animation(...)` emit a `DeprecationWarning` pointing users at `.animate()`? ### 3. Downstream artifacts - `stubs/mcrfpy.pyi` should reflect every item in the catalog with correct type annotations - `docs/API_REFERENCE_DYNAMIC.md` and `docs/api_reference_dynamic.html` should be regenerated - `docs/mcrfpy.3` (man page) should be regenerated ### 4. Commit hygiene One commit per meaningful batch. Reference this issue. ## Not in scope - Writing new tutorial content (separate effort, see #167) - Changing external prose docs in `docs/` beyond what the audit covers - 3D / Experimental type documentation (exempt from 1.0 freeze) ## Why now Part of Track 1 (API Freeze) in the current `ROADMAP.md`. Settling the documentation surface is a precondition for the freeze itself — you can't commit to a stable API if the public-facing docs don't describe it accurately. ## Related - `docs/api-audit-2026-04.md` — source document - `CLAUDE.md` → "Documentation Macro System" — how MCRF_* macros work - `tools/generate_all_docs.sh` — the single-command regeneration path

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

john/McRogueFace#314

No description provided.

Rows
Columns