docs(comparison): accuracy pass on the feature grid (caveats + compiler-verified marks)

[math3usmartins]

An accuracy pass over the feature grid in docs/guides/comparison.md

No code changes; docs only. Nothing moved between "supported" and "missing"
in the wrong direction -- the grid just stops overstating features that work
but carry real caveats, and one cross-language mark that was simply wrong is
corrected.

xphp column

• New row: type-argument inference. xphp has none -- the ::<> turbofish is
  mandatory on every generic call (omitting it is a compile error), unlike
  TypeScript/Kotlin/Rust, which infer. Rust is the close parallel: same
  ::<> syntax, but there it is the disambiguation fallback over default
  inference. Marked absent for xphp, with a short note.

• Five rows moved from a plain "supported" to "supported with caveats",
  each with the caveat named in the cell and a new "Supported with caveats"
  section linking the full write-up in caveats.md:

• Generic closures / arrows: no $this capture, no static function
  closures, and reflection/serializers see the dispatcher rewrite.

• Typed closure signatures: parameter/return/property positions only,
  not as a generic argument or bound.

• Generic functions / methods: no inference, and a turbofish can't
  forward a method-level parameter, target another generic template, or
  use static::/parent::.

• Declaration-site variance: violations inside trait-used methods go
  unchecked; class-level only.

• Real subtype edges: some covariant upcasts of erased method-generics
  are unschedulable, and self-reintroducing derivations may not
  converge (the celebratory subsection now points at this too).

Other-language columns

Checked by compiling generic snippets in throwaway containers rather than
asserting from memory: TypeScript 7.0.2, Rust 1.97.1, Kotlin 1.4.10. The
RFC column has no implementation to run, so its claims were checked against
the RFC text.

• RFC typed closure signatures: was marked supported, but the bound-erased
  generics RFC has no structural closure/callable signature types (it lists
  them as future work). Corrected to absent; PHP has only untyped callable
  / \Closure.
• Kotlin reified T: now a caveat -- class Box<reified T> fails with "only
  type parameters of inline functions can be reified", so reification is
  inline-fun-only.
• Generic enums: neither a Kotlin enum class nor a TS enum can be
  generic (compiler-verified); both keep their check but note the real
  mechanism (sealed classes / discriminated unions).

Everything else in the TS, Rust, and Kotlin columns was confirmed correct
by the same compile checks (declaration-site variance, variadic tuples,
union bounds, type aliases, associated types, use-site variance,
reified/monomorphic T, and specialization-needs-nightly).

[greptile-apps]

Greptile Summary

This docs-only PR is an accuracy pass over the feature grid in docs/guides/comparison.md. It stops overstating features that work but carry real caveats, corrects three cells in the TS/Kotlin/RFC columns that were verified wrong by compiling against actual compilers and reading the RFC text, and adds a new "Supported with caveats" prose section that links every ⚠️ mark back to the full write-up in caveats.md.

• Five xphp features (generic closures, typed closure signatures, generic functions/methods, declaration-site variance, real subtype edges) are downgraded from plain ✅ to ⚠️ with a one-line caveat summary in the cell and a new detailed subsection linking all relevant anchors in caveats.md — all nine anchor links verified correct against actual section headings.
• A new "Type-argument inference" grid row is added (xphp ❌, RFC ❌ with different semantics, TS/Kotlin/Rust ✅) with an explanatory paragraph distinguishing xphp's mandatory turbofish from Rust's optional-fallback turbofish.
• Three other-language corrections: RFC typed closure signatures ✅→❌ (listed as future work in the RFC text), Kotlin reified T ✅→⚠️ (class-level type parameters can't be reified, only inline-fun parameters), and TS/Kotlin generic enums annotated to clarify the actual mechanism (discriminated unions / sealed classes).

Confidence Score: 5/5

Docs-only change with no code modifications; all nine caveats.md anchor links verified against actual section headings, and the other-language corrections are backed by compiler runs described in the PR.

The change is purely documentation — no logic, no runtime behavior, no schema. Every corrected cell in the grid has a stated verification method (compiler run or RFC text check), and all internal anchor links resolve correctly to existing sections in caveats.md.

Files Needing Attention: No files require special attention.

Important Files Changed

Filename	Overview
docs/guides/comparison.md	Accuracy pass on the feature grid: five xphp rows promoted from ✅ to ⚠️ with named caveats, one new "type-argument inference" row added, three other-language cells corrected (RFC typed closures ✅→❌, Kotlin reified T ✅→⚠️, TS/Kotlin generic enums annotated with actual mechanism). New "Supported with caveats" prose section added with verified caveats.md anchor links.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Feature Grid Cell] --> B{xphp status?}
    B -->|"✅ fully supported"| C[No further action]
    B -->|"⚠️ supported with caveats"| D[Cell gets one-line caveat note]
    B -->|"❌ absent"| E[What's missing section]
    D --> F[Supported with caveats section]
    F --> G1[Generic closures + arrows]
    F --> G2[Typed closure signatures]
    F --> G3[Generic functions/methods]
    F --> G4[Declaration-site variance]
    F --> G5[Real subtype edges]
    G1 & G2 & G3 & G4 & G5 --> H[Full write-up in caveats.md]

Loading

_{Reviews (3): Last reviewed commit: "docs(comparison): link the self-reintrod..." | Re-trigger Greptile}