Repository navigation
Document normative interface contracts and preserve their PHPDoc #72
Description
The public ProcessRunner PHPDoc describes method behavior inside parameter tags and omits clear method summaries, output/failure choices and implementer responsibilities. ResultProcessRunner adds lossless capture but needs a consistent documented contract and usage decision.
Scope:
- Audit the repository's own interfaces against implementations, callers and behavioral tests.
- Document method summaries and semantic preconditions/postconditions, side effects and failure behavior using RFC 2119/8174 terms sparingly and accurately.
- Explain capture versus run versus optional captureResult with examples and limits; subprocess execution is not a filesystem sandbox.
- Preserve namespaces, class/interface names, signatures and existing behavior.
- Document the uppercase normative-word convention in the canonical RST documentation.
- Add real formatter/Rector regressions retaining descriptive normative PHPDoc and inheritance markers, without promising arbitrary consumer-selected Rector rules preserve documentation.
Acceptance: every own interface method has a useful summary and tested semantic contract; examples agree with the installed API; formatting check is read-only and explicit fix preserves the documentation and is idempotent; qualified native semantic-rule preview/application preserves it; current-head tests/reviews pass.
Related: #10 owns structured ECS/Rector payloads and CLI JSON; that broader feature is not duplicated or closed by this documentation slice. RFC sources: https://www.rfc-editor.org/rfc/rfc2119 and https://www.rfc-editor.org/rfc/rfc8174 .
Activity
coisa commentedon Oct 27, 2026
Delivered by PR #74, merged as
b352cdec815d3eda9c0fd951710fe2051b129836. The merge tree25c2377b442af361073dd66d3fdf941a13bc11d5exactly matches the reviewed and tested candidate.The interfaces now have concise implementer-independent contracts, a canonical guide explains capture/run/captureResult, timeout tags use supported float with their semantic description, and ECS/Rector regressions preserve meaningful normative documentation. Names, signatures and runtime behavior remain unchanged. Local composer check passed 157 tests / 1,239 assertions with one explicit unavailable-runtime skip; current-head hosted PHP 8.3/8.4/8.5, reusable check, Changelog and CodeQL passed before merge, with Codex code/security receipts and full CodeRabbit coverage of
7b9f813without pending findings. Post-merge main CI is being followed separately.The documented phpDocumentor inheritance limitation remains explicit; this delivery does not claim arbitrary renderer/configuration equivalence or close broader structured-report work in #10.