docs: clean up API documentation (#1763)

Author: leandrocp

AGENTS.md

@@ -351,7 +351,7 @@ Docs, specs, and examples are not cleanup work for later. They are part of the f
 
 - Keep README files, package docs, examples, and generated references consistent with the shipped behavior.
 - If a change affects public API, behavior, configuration, or generated outputs, update the relevant docs and examples in the same PR.
-- Significant breaking changes must add a migration guide under `docs/content/migrate/` (`/migrate` on the docs site). Explain what breaks and how to update existing code or configuration. Usage and reference pages describe the current behavior and link to the guide. Move existing upgrade instructions there rather than deleting them.
+- Add migration guides only when explicitly requested. Keep replacement guidance in code deprecation annotations. Usage and reference pages describe the current API.
 - Use the `humanizer` skill when writing or editing documentation.
 
 Prefer concrete explanations over marketing language. Show the real API. Keep examples runnable.
@@ -382,9 +382,9 @@ were Zig. Every sentence of it is bloat in a place with a low budget for it.
   binding crate's own doc comments, a commit message. `html_span_attrs` in
   `lumis_nif` explains the call-frequency split at length, correctly — that is a
   contributor's file.
-- **Cross-runtime pointers are not this.** "The counterpart of `Language::guess`
-  in Rust and `guessLanguage()` in JavaScript" helps someone moving between the
-  packages Lumis publishes, and stays.
+- **Keep API references specific to their runtime.** Describe the function
+  directly; omit comparisons to equivalent functions in other runtimes.
+  Cross-runtime API mappings belong in contributor documentation.
 
 This applies to every published surface: package docs, READMEs, `usage-rules.md`,
 and `docs/content/`. It came out of an ANSI helper module whose moduledoc opened

crates/lumis-core/src/formatter/html.rs

@@ -571,9 +571,7 @@ pub(crate) fn write_escaped(output: &mut dyn Write, text: &str) -> io::Result<()
 /// loaded with [`crate::themes::from_json`]. Neither is a generated constant, so
 /// both are escaped here rather than interpolated raw.
 ///
-/// The escape set is the same as [`escape`], which is what `escapeAttr` in
-/// `packages/javascript/lumis/src/formatter/html.ts` covers, so the two runtimes
-/// answer the same for the same input. Escaping is safe for CSS in an attribute
+/// The escape set is the same as [`escape`]. Escaping is safe for CSS in an attribute
 /// because the HTML parser decodes the entity before the CSS parser sees it, so
 /// `font-family: 'Fira Code'` survives the round trip.
 pub fn escape_attr(value: &str) -> String {

crates/lumis-core/src/languages.rs

@@ -378,9 +378,6 @@ macro_rules! define_languages {
 
         /// Every compiled-in language and what the catalog knows about it,
         /// sorted by id.
-        ///
-        /// Elixir's `Lumis.Languages.available/0` and JavaScript's
-        /// `languages.available()` return this same record.
         pub fn available_languages() -> Vec<LanguageInfo> {
             let mut languages: Vec<LanguageInfo> = Language::iter().map(|l| l.info()).collect();
             languages.sort_unstable_by_key(|language| language.id);

crates/lumis/src/highlight.rs

@@ -105,9 +105,6 @@ static DEFAULT_STYLE: LazyLock<Arc<Style>> = LazyLock::new(|| Arc::new(Style::de
 
 /// Options for one highlighting operation.
 ///
-/// The counterpart of the `options` argument to JavaScript's `highlight()` and
-/// `highlightEvents()`.
-///
 /// `'a` is the annotation data's lifetime; `'c` is the cancellation flag's.
 /// Returned events borrow only the annotations, so they can outlive the flag.
 ///

docs/content/migrate/api-modules.mdx

@@ -8,8 +8,6 @@ release numbers, so the guides are grouped by runtime or integration.
 
 | Existing code | Guide |
 | --- | --- |
-| JavaScript or Elixir root catalog and parser helpers | [Language and theme modules](/migrate/api-modules) |
-| Rust `themes::choose_theme` calls | [Theme matching](/migrate/theme-matching) |
 | Elixir 0.6, or parser downloads from before 0.9 | [Elixir upgrades](/migrate/elixir) |
 | HTML line divs or helpers that return line terminators | [HTML line markup](/migrate/html-lines) |
 | JavaScript-only custom parser and query definitions | [JavaScript custom languages](/migrate/javascript) |

docs/content/migrate/index.mdx

@@ -2,8 +2,6 @@
   "title": "Migrate",
   "pages": [
     "index",
-    "api-modules",
-    "theme-matching",
     "elixir",
     "html-lines",
     "javascript",

docs/content/migrate/meta.json

@@ -35,9 +35,6 @@ let theme = themes::closest(&colors);
 assert_eq!(theme.map(|theme| theme.name.as_str()), Some("modus_vivendi"));
 ```
 
-Existing callers of `choose_theme` should follow the
-[rename guide](/migrate/theme-matching).
-
   </Tab>
   <Tab value="Elixir">
 

docs/content/migrate/theme-matching.mdx

@@ -181,8 +181,7 @@ Useful when rendering user-provided content or pasted snippets.
 ## Metadata APIs
 
 Language helpers live in `@lumis-sh/lumis/languages`, and theme helpers live in
-`@lumis-sh/lumis/themes`. Old root imports still work but are deprecated; see the
-[module migration guide](/migrate/api-modules).
+`@lumis-sh/lumis/themes`.
 
 Useful for dropdowns, config validation, and docs tooling:
 
@@ -195,7 +194,7 @@ Useful for dropdowns, config validation, and docs tooling:
 ## Runtime notes
 
 - every runtime loads the same per-language parser WASM; what differs is the engine that runs it
-- on Node, `@lumis-sh/lumis` runs those parsers and the highlighting walk under Wasmtime in the same Rust code as the Lumis CLI and Elixir bindings; built-in formatters normally render there too, while custom formatters assemble events in JavaScript and an async call that may need a JavaScript resolver stays on the main thread
+- on Node, `@lumis-sh/lumis` runs those parsers and the highlighting walk under Wasmtime; built-in formatters normally render there too, while custom formatters assemble events in JavaScript and an async call that may need a JavaScript resolver stays on the main thread
 - browsers, and any platform with no prebuilt addon, run them under the host's own WebAssembly through `web-tree-sitter`, and walk and format in JavaScript
 - the addon is prebuilt for macOS arm64 and x64, Linux arm64 and x64 against both glibc and musl, and Windows arm64 and x64; npm installs the one matching the host, so Alpine and other musl images get the same runtime as a glibc host
 - `runtimeKind()` returns `'native'` or `'wasm'` if you need to confirm which one an install resolved