Docs cleanup: merge duplicate namespace dirs (date/datetime, network/networking) #38

New issue

Closed

opened 2026-08-30 12:50:39 +02:00 by orkun · 1 comment

orkun commented

2026-08-30 12:50:39 +02:00

Owner

Problem

The per-symbol documentation source under docs/language/ has overlapping /
duplicated namespace directories that are confusing and error-prone:

docs/language/date and docs/language/datetime
docs/language/network and docs/language/networking

Two dirs covering the same area invites drift: a symbol gets documented in one and
not the other, and the generated site ends up with near-duplicate or half-empty
sections. Since the docs pipeline treats docs/language/** as the single source
of truth, this ambiguity propagates straight to the published site.

Proposal

Audit date vs datetime and network vs networking; pick one canonical
directory per namespace and merge/redirect the other.
Align the directory names with the actual runtime namespaces (DateTime,
Duration, Net/Network — whatever the language actually exposes).
Add a docgen check (see the tools-in-Ludic issue) that fails if two dirs map
to the same namespace, so this can't reappear.

Acceptance criteria

One directory per documented namespace; duplicates merged.
Dir names match the real runtime namespaces.
docgen guards against duplicate-namespace dirs.

Found during the repository-cleanup / DX pass.

## Problem The per-symbol documentation source under `docs/language/` has **overlapping / duplicated namespace directories** that are confusing and error-prone: - `docs/language/date` **and** `docs/language/datetime` - `docs/language/network` **and** `docs/language/networking` Two dirs covering the same area invites drift: a symbol gets documented in one and not the other, and the generated site ends up with near-duplicate or half-empty sections. Since the docs pipeline treats `docs/language/**` as the single source of truth, this ambiguity propagates straight to the published site. ## Proposal - Audit `date` vs `datetime` and `network` vs `networking`; pick **one canonical directory per namespace** and merge/redirect the other. - Align the directory names with the actual runtime namespaces (`DateTime`, `Duration`, `Net`/`Network` — whatever the language actually exposes). - Add a `docgen` check (see the tools-in-Ludic issue) that fails if two dirs map to the same namespace, so this can't reappear. ## Acceptance criteria - [ ] One directory per documented namespace; duplicates merged. - [ ] Dir names match the real runtime namespaces. - [ ] `docgen` guards against duplicate-namespace dirs. Found during the repository-cleanup / DX pass.

orkun added the

priority:low

area:docs

cleanup

labels 2026-08-30 12:50:39 +02:00

orkun referenced this issue from a commit

2026-08-30 15:46:48 +02:00

docs: merge duplicate networking namespace dirs; guard against recurrence

orkun closed this issue

2026-08-30 15:46:48 +02:00

orkun commented

2026-08-30 15:47:45 +02:00

Author

Owner

Done in 3bab2d2.

Audit changed the plan for one of the two flagged pairs:

date vs datetime — NOT duplicates. Date is calendar days since the epoch; DateTime is instants (seconds since the epoch). They are distinct runtime namespaces with distinct readers, so both were kept.
network vs networking — a real duplicate, resolved. Every other stdlib area documents only its namespace (World.*, Screen.*, …), never the bare builtins it lowers to. Networking alone also documented the low-level net_*/builtin forms under networking/, duplicating the Network.* pages under network/. Removed networking/; network/ (the Network namespace — the compiler lowers Network.send->net_send and the LSP exposes it) is canonical. The @Sync/@Owned framing from the old section was folded into network/_section.md so no context is lost. Dropped the networking key from docgen inventory.

AC3 guard: tools/docgen/check.py now fails if any ns: is documented from more than one directory, or if two sections share an id or case-folded title — a duplicate-namespace split can't silently reappear. Verified it fires on a synthetic dup.

gen.py + check.py green (34 sections, 365 symbols).

Done in 3bab2d2. Audit changed the plan for one of the two flagged pairs: - **date vs datetime** — NOT duplicates. `Date` is calendar days since the epoch; `DateTime` is instants (seconds since the epoch). They are distinct runtime namespaces with distinct readers, so both were kept. - **network vs networking** — a real duplicate, resolved. Every other stdlib area documents only its namespace (`World.*`, `Screen.*`, …), never the bare builtins it lowers to. Networking alone also documented the low-level `net_*`/builtin forms under `networking/`, duplicating the `Network.*` pages under `network/`. Removed `networking/`; `network/` (the `Network` namespace — the compiler lowers `Network.send`->`net_send` and the LSP exposes it) is canonical. The `@Sync`/`@Owned` framing from the old section was folded into `network/_section.md` so no context is lost. Dropped the `networking` key from docgen inventory. AC3 guard: `tools/docgen/check.py` now fails if any `ns:` is documented from more than one directory, or if two sections share an id or case-folded title — a duplicate-namespace split can't silently reappear. Verified it fires on a synthetic dup. gen.py + check.py green (34 sections, 365 symbols).