# Implementation Plan: Full Review — Documentation Repair

**Track ID:** review-docs_20260318
**Spec:** [spec.md](./spec.md)
**Created:** 2026-03-18
**Status:** [x] Complete

## Overview

Fix all documentation correctness issues in two phases: source code docstrings first (Python files, covered by Pyright), then MkDocs content (Markdown files). Use `uv run mkdocs serve` to verify rendering after changes.

---

## Phase 1: Source Code Docstring Fixes

Fix misleading docstrings in Python source files that affect IDE help, generated API docs, and type checker context.

### Tasks

- [x] Task 1.1: Update `Device.connect()` docstring in `base.py:514` — clarify that state is initialized in `__aenter__()`, not on return from `connect()`; add note that `async with` is required for guaranteed initialized state (D-H2, AR-M4)
- [x] Task 1.2: Update `discover_mdns()` docstring in `api.py` — change "yields Light devices" to "yields Device instances (Light, MatrixLight, MultiZoneLight, etc.)" (D-H1)
- [x] Task 1.3: Update `from_ip()` docstring in `base.py:449` — add missing `max_retries` parameter documentation (D-L4)
- [x] Task 1.4: Add `Raises` section to exception class docstrings in `exceptions.py` — document when each exception is raised (D-L3)
- [x] Task 1.5: Run benchmarks and save as `review-docs_20260318-Phase1`: `uv run pytest tests/benchmarks/ -m benchmark --no-cov --benchmark-save=review-docs_20260318-Phase1`

### Verification

- [ ] `uv run pyright` — no type errors
- [ ] `uv run ruff check .` — no lint errors

---

## Phase 2: MkDocs Content Fixes

Fix all Markdown documentation correctness issues.

### Tasks

- [x] Task 2.1: Fix Python version references — change "Python 3.11+" to "Python 3.10+" in: `README.md` badge, `docs/index.md`, `docs/faq.md`, `docs/getting-started/installation.md` (D-H3)
- [x] Task 2.2: Fix `docs/getting-started/installation.md` — replace `cd lifx` with `cd lifx-async`; fix non-existent API examples (D-H4, D-L5)
- [x] Task 2.3: Fix `docs/getting-started/quickstart.md:195` — correct `breathe(cycles=0)` example; document valid range for cycles parameter; remove or fix `Colors.WARM_WHITE`/`Colors.COOL_WHITE` references (replace with `Colors.WARM`/`Colors.COOL`) (D-M1, D-M2)
- [x] Task 2.4: Fix `docs/faq.md` — replace `find_lights()` with `find_by_label()`; fix `Colors.WARM_WHITE`/`Colors.COOL_WHITE`; fix `conn.request_response()` reference; correct packet type import paths (D-H4, D-M2)
- [x] Task 2.5: Fix `docs/api/exceptions.md` — replace `light.connect()` / `light.disconnect()` with correct `async with` pattern; fix packet import paths in code examples (D-H4, D-L1)
- [x] Task 2.6: Fix `docs/api/index.md` — remove `light.connect()` / `light.disconnect()` from "bad practice" examples; replace with correct patterns (D-L1)
- [x] Task 2.7: Update `docs/index.md` — fix test count from "over 700" to "2425+"; fix support URL from `lifx.readthedocs.io` to `https://djelibeybi.github.io/lifx-async/` (D-L2, D-M5)
- [x] Task 2.8: Fix `README.md` — fix support URL from `lifx.readthedocs.io` to correct docs URL (D-L8)
- [x] Task 2.9: Update `docs/architecture/overview.md` — expand from 4-layer to 8-layer diagram (add Animation, Effects, Theme); update concurrency model from `_request_lock` description to background receiver + queue-based correlation (D-M3, D-M4)
- [x] Task 2.10: Run benchmarks and save as `review-docs_20260318-Phase2`: `uv run pytest tests/benchmarks/ -m benchmark --no-cov --benchmark-save=review-docs_20260318-Phase2`

### Verification

- [ ] `uv run mkdocs build` — builds without errors or warnings
- [ ] Manual spot-check: open `docs/getting-started/quickstart.md` in `uv run mkdocs serve` and verify all code examples reference real API methods
- [ ] `uv run --frozen pytest` — full test suite passes (docs changes should not affect tests)

---

## Final Verification

- [ ] All acceptance criteria in spec.md met
- [ ] `uv run mkdocs build` — clean build, no warnings
- [ ] `uv run --frozen pytest` — all tests pass
- [ ] `uv run pyright` — clean
- [ ] No references to non-existent APIs in any `docs/` file
- [ ] Python 3.10+ shown consistently across all docs
- [ ] Ready for review

---

_Generated by Conductor. Tasks will be marked [~] in progress and [x] complete._
