Document foundation APIs and usage contracts
epic-screen-reader-support-foundation-task-014 — Write developer documentation covering: the sensitive field registry lookup API and how to register new fields at runtime; the accessibility settings repository stream contract and default values; how to use SemanticsWrapperWidget with all parameter combinations and role constants; the screen reader detection stream lifecycle; and the SemanticsServiceFacade announcement API with polite vs assertive priority guidance.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
Write dartdoc comments directly on each public class/method so `dart doc` generates accurate API reference automatically. Supplement with a `docs/accessibility_foundation.md` markdown file covering architecture decisions and cross-API workflows. For the sensitive field registry, clearly state thread-safety guarantees (or lack thereof) since this is often the source of bugs. For the announcement API, include a priority decision table: use assertive only for errors or critical status changes; use polite for progress updates and confirmations.
Cross-reference the WCAG 2.2 AA criteria satisfied by each API to help reviewers validate compliance. Avoid documenting internal implementation details — focus on contracts (inputs, outputs, side effects, disposal).
Testing Requirements
No automated tests for documentation itself. Verify all code examples by running them in a test harness: place each snippet in a flutter_test widget test and confirm it compiles and executes without errors. One integration smoke test should import each documented API and call it with the documented signature to catch API drift. Mark these as 'doc-smoke' tests in the test suite.
Flutter's SemanticsService behaves differently between iOS (VoiceOver) and Android (TalkBack) in edge cases — e.g., announcement queuing, focus-gain timing, and attribute support. If the facade does not correctly abstract these differences, announcements may be silent or misfired on one platform, causing regression on the other platform to go unnoticed until device testing.
Mitigation & Contingency
Mitigation: Write platform-divergence unit tests early using SemanticsServiceFacade mocks. Validate announcement delivery on a physical iPhone (VoiceOver) and Android device (TalkBack) at the end of each sprint. Document known platform differences in the facade's inline API comments.
Contingency: If a platform difference cannot be abstracted cleanly, expose a platform-specific override path in the facade and implement targeted workarounds per platform, accepting the added complexity in exchange for correct behaviour.
Accessibility preferences stored in local storage may need new fields as higher-tier epics are implemented (e.g., announcement verbosity, sensitive-field guard toggle). Schema changes to an already-persisted store risk data migration failures or silent defaults on existing installs, breaking user preferences.
Mitigation & Contingency
Mitigation: Design the AccessibilitySettingsRepository with a versioned JSON schema from the start, using merge-with-defaults on read so new fields fall back gracefully. Define the full expected field list upfront based on all downstream epic requirements before writing the first record.
Contingency: If migration fails on a live install, fall back to full reset-to-defaults with a one-time in-app notification informing the user that accessibility preferences have been reset and inviting them to reconfigure.