From cb24dc5073f1f4f5dce701549447c14382af5fda Mon Sep 17 00:00:00 2001 From: Matheus Martins Date: Thu, 4 Jun 2026 16:49:52 +0000 Subject: [PATCH] docs: sync public docs with single-package layout Catch up the README and docs/ after the split-repos collapse: drop the stale `core/` prefix from prose and internal links, surface `compile`'s optional `target`/`cache` defaults in the README argument table, frame the README's sample output as illustration (real names are hashed), and remove dangling references to features that now live in other repos (LSP path, `--lint` headless CLI). Also fix four pre-existing broken relative links found while sweeping the doc tree. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 21 ++++++++++----------- docs/compiler.md | 24 ++++++++++++------------ docs/roadmap.md | 1 - docs/type-system/comparison.md | 6 ++---- docs/type-system/generics/index.md | 6 +++--- 5 files changed, 27 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index be26ebe..2be9534 100644 --- a/README.md +++ b/README.md @@ -141,15 +141,17 @@ $users = new Collection( vendor/bin/xphp compile ``` -| Argument | Purpose | -|------------|--------------------------------------------------------------------------------------| -| `` | Directory of `.xphp` files (PSR-4 layout) | -| `` | Where rewritten `.php` files land -- your user code with generic call sites replaced | -| `` | Where specialized classes live | +| Argument | Required | Default | Purpose | +|------------|----------|----------------|--------------------------------------------------------------------------------------| +| `` | yes | -- | Directory of `.xphp` files (PSR-4 layout) | +| `` | no | `dist` | Where rewritten `.php` files land -- your user code with generic call sites replaced | +| `` | no | `.xphp-cache` | Where specialized classes live | p.s. you can `gitignore` files in `` and `` as they can be generated in your CI/CD pipeline. -#### Sample output +#### Sample output + +The sample below uses a readable name (`Collection_User`) for clarity. The compiler actually emits hashed FQNs of the form `\XPHP\Generated\App\Collection\T_` -- see the [generics reference](docs/type-system/generics/index.md) for the real scheme. ```php // /Generated/Collection_User.php @@ -157,9 +159,6 @@ namespace XPHP\Generated; use App\User; -// p.s. in reality it uses a hash in the class name, -// but developers won't touch that, -// only php runtime will see the hashed names. class Collection_User { private array $items; @@ -205,5 +204,5 @@ Meaning every place where generics are declared or used is converted into normal ## See also -- [Type-system comparison](core/docs/type-system/comparison.md) -- [Full generics reference](core/docs/type-system/generics/index.md) +- [Type-system comparison](docs/type-system/comparison.md) +- [Full generics reference](docs/type-system/generics/index.md) diff --git a/docs/compiler.md b/docs/compiler.md index 75256bb..1e8c911 100644 --- a/docs/compiler.md +++ b/docs/compiler.md @@ -1,23 +1,25 @@ # How the xphp compiler works -Narrative walkthrough of the `core/` pipeline -- what `bin/xphp compile` +Narrative walkthrough of the compile pipeline -- what `bin/xphp compile` does between reading `.xphp` source and writing vanilla `.php` files that any stock PHP 8.4 runtime can execute. Each phase is paired with a Mermaid diagram so the same information is available both visually and in prose. For the feature inventory ("what does xphp support today?") see -[generics reference](generics/index.md). For the strategic comparison -against TypeScript / Kotlin / Rust see [comparison](type-system/comparison.md). -For the forward-looking inventory see [roadmap](roadmap.md). +[generics reference](type-system/generics/index.md). For the strategic +comparison against TypeScript / Kotlin / Rust see +[comparison](type-system/comparison.md). For the forward-looking inventory +see [roadmap](roadmap.md). --- ## Pipeline overview -`bin/xphp compile ` runs a single +`bin/xphp compile [target-dir] [cache-dir]` runs a single function -- [`Compiler::compile()`](../src/Transpiler/Monomorphize/Compiler.php) --- that orchestrates five phases. The data flows top-down: source bytes +-- that orchestrates five phases. Only `` is required; `[target-dir]` +defaults to `dist` and `[cache-dir]` defaults to `.xphp-cache`. The data flows top-down: source bytes turn into AST, the AST populates a Registry and a TypeHierarchy, a fixed-point loop expands every concrete instantiation into a specialized class file, and finally the rewritten user code lands in the target @@ -119,8 +121,8 @@ Two parser entry points exist: source. - `parseTolerantWithMap()` -- recovers from trailing parse errors by feeding the stripped source through nikic's error-handler- - collecting mode. Used by the LSP path so mid-edit source still - yields useful results. + collecting mode. Used when callers need partial results from + incomplete source. --- @@ -370,16 +372,14 @@ birthday collisions are impossible at any practical project size. `ByteOffsetMap` carries the bytes-stripped-and-where info so any diagnostic span computed after the strip can be translated back to -the original `.xphp` source. The map gets serialised through to -the LSP layer too, so editor squiggles land on the right column -even though the parsed AST was built from stripped source. +the original `.xphp` source. --- ## Class roster Every class under -[`core/src/Transpiler/Monomorphize/`](../src/Transpiler/Monomorphize/), +[`src/Transpiler/Monomorphize/`](../src/Transpiler/Monomorphize/), grouped by role. ```mermaid diff --git a/docs/roadmap.md b/docs/roadmap.md index 4ecfeff..233a0ec 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -31,7 +31,6 @@ timeline : XPHP_HASH_LENGTH configurable (16..64) Developer experience : PSR-4 fixtures - : --lint headless CLI for CI (file,line,col error output) section Next Type system depth : default type parameters diff --git a/docs/type-system/comparison.md b/docs/type-system/comparison.md index 9fb3cac..61c5000 100644 --- a/docs/type-system/comparison.md +++ b/docs/type-system/comparison.md @@ -105,10 +105,8 @@ class) is supported. `$obj->method(...)` requires knowing the static type of properties, the static type is usually known at the call site; the unsolved part is the dispatch table when `$obj` is a union / intersection / interface. -Tracked in `core/roadmap.md` under "Next". The LSP already substitutes -type-args at instance call sites for hover / signature help / inlay hints -- -that's display-only inference; the compiler-level lowering for runtime dispatch -is the gap. +Tracked in the [roadmap](../roadmap.md) under "Next". The compiler-level +lowering for runtime dispatch is the gap. ### 5. Reified type parameters diff --git a/docs/type-system/generics/index.md b/docs/type-system/generics/index.md index a0d537d..c08f906 100644 --- a/docs/type-system/generics/index.md +++ b/docs/type-system/generics/index.md @@ -4,7 +4,7 @@ This document covers how `xphp` implements generics: what the compiler emits, what's supported today, the naming scheme for generated classes, and the trade-offs the monomorphization model accepts. -For the broader project context, see the [README](/README.md). +For the broader project context, see the [README](../../../README.md). --- @@ -23,7 +23,7 @@ For comparison, Rust does also apply monomorphization. Kotlin and TypeScript don't do that, and there they have no runtime safety. Variance annotations based on monomorphization become real subtype edges between -specialized classes -- that's in the [roadmap](../roadmap.md). +specialized classes -- that's in the [roadmap](../../roadmap.md). --- @@ -263,5 +263,5 @@ intentional. ## Type-system comparison -See a [side-by-side comparison](./comparison.md) against TypeScript, Kotlin, +See a [side-by-side comparison](../comparison.md) against TypeScript, Kotlin, and Rust -- including the features `xphp` doesn't have yet.