Z/release docs deprecations

[zanbaldwin]

No description provided.

[greptile-apps]

Greptile Summary

This documentation update leaves two user-facing reference mismatches: the installation guide omits a Composer-required IPv6 capability, and two API-table entries advertise an argument not guaranteed by the documented factory interfaces. Both are non-blocking documentation corrections.

Confidence Score: 4/5

Safe to merge because the confirmed issues are non-blocking documentation inaccuracies, though correcting them will prevent avoidable installation and API-usage confusion.

The review confirmed two documentation issues through focused checks against the package manifest, public interface declarations, and concrete implementation signatures.

Files Needing Attention: docs/02-installation.md needs the IPv6 requirement documented, and docs/10-api.md needs the two factory signatures corrected or marked as Multi-specific.

T-Rex Logs

What T-Rex did

• T-Rex produced and linked a proof for the first posted P2 finding, including a shell script artifact and its review log.
• T-Rex produced and linked a second P2 finding proof, including a shell script and two logs linked to the review comment.
• T-Rex validated the contract by confirming that composer.json requires php-ipv6 >= 7.1 and that the docs do not mention IPv6, with the check exiting 0.
• T-Rex posted another P2 finding proof as part of the ongoing review.
• T-Rex completed a second contract-validation pass by inspecting the factory-contract scripts and related PHP type checks, resulting in exit code 0 and a passed mismatch assertion.

_{Ran code and verified through T-Rex}

Comments Outside Diff (4)

1. docs/02-installation.md, line 5-7 (link)

   Document IPv6 Support

   This non-blocking installation guidance omits IPv6 support even though composer.json requires the php-ipv6 platform capability. A PHP environment can meet the documented PHP-version and ctype requirements but still be rejected during installation, creating an avoidable setup failure. Document IPv6 support alongside the other requirements.

   Artifacts

   
   

   Evidence from the check

   • Python source executed from the repository to compare HEAD and working-tree documentation lines with Composer requirements, confirming the tested conditions.

   Command output from the check

   • Captured command output shows `php-ipv6` is declared, documentation lines 5–7 omit IPv6, the lines match HEAD, and the check exited successfully.

   

   _{Ran code and verified through T-Rex}

2. docs/10-api.md, line 14-17 (link)

   Correct Factory Signatures

   This non-blocking API reference documents an optional $strategy for FactoryInterface::tryFromIntegerString() and Factory4Interface::tryFromInteger(), but both public interfaces accept only the numeric argument. The optional strategy exists only on Multi, so consumers relying on the documented interface contract may write calls that are not supported by their declared factory type. Remove [$strategy] from these interface rows or explicitly identify it as Multi-only behavior.

   Knowledge Base Used: Public API contracts

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   Artifacts

   
   

   Evidence from the check

   • The shell script compared the documentation, shared interfaces, Multi implementation, and related-repository calls; it is the executable source used for the check.

   Command output from the check

   • This command capture contains the exact source of the shell script that was executed to inspect signatures and related usage; it provides reproducible verification input.

   Command output from the check

   • The executed check exited 0 and shows the documentation's optional strategy, one-argument interface declarations, two-argument Multi declarations, and no direct related-repository numeric factory usage; the mismatch is confirmed.

   

   _{Ran code and verified through T-Rex}

3. General comment

   Installation requirements omit Composer's required IPv6 platform capability

   • Bug
     • composer.json:29 requires php-ipv6 at >=7.1, but docs/02-installation.md:5–7 describes only PHP 7.1+ and the ctype extension. A user on a PHP environment without IPv6 support can satisfy the stated documentation requirements but be rejected by Composer.
   • Cause
     • The documentation's system-requirements bullet does not include the manifest's php-ipv6 platform requirement.
   • Fix
     • Update the system-requirements documentation to state that PHP must have IPv6 support (in addition to PHP 7.1+, 64-bit support, and ctype).

   _{Ran code and verified through T-Rex}

4. General comment

   API reference overstates strategy support on factory-interface methods

   • Bug
     • docs/10-api.md:14 documents FactoryInterface::tryFromIntegerString(string $integer, [$strategy]), while src/Contracts/FactoryInterface.php:80 declares only tryFromIntegerString(string $integer). Likewise, docs/10-api.md:17 documents Factory4Interface::tryFromInteger(int $integer, [$strategy]), while src/Contracts/Factory4Interface.php:29 declares only tryFromInteger(int $integer). The optional strategy is concrete Multi-only behavior (src/Version/Multi.php:177 and :196), not behavior guaranteed by these public contracts. ip-doctrine has no direct use of these interfaces or numeric factory methods, and its types call IP::factory($ip), so no direct downstream compatibility impact was observed there.
   • Cause
     • The API table generalizes Multi's optional embedding-strategy parameter to FactoryInterface and Factory4Interface contract rows, although those interfaces do not declare it.
   • Fix
     • Either remove [$strategy] from documentation lines 14 and 17, or change the table to identify those parameters as Multi-specific. If the intended API is contract-wide strategy support, add compatible optional strategy parameters to the relevant interfaces and implementations, with an explicit compatibility review.

   _{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: 598bbce | Re-trigger Greptile}