From 75c9cd8138116b99df984674a01a958c18e4063c Mon Sep 17 00:00:00 2001
From: overlookmotel <557937+overlookmotel@users.noreply.github.com>
Date: Tue, 24 Feb 2026 16:04:11 +0000
Subject: [PATCH] docs(parser): improve doc comments for `ParserConfig` and
 `LexerConfig` (#19682)

Improve documentation for the config types added in #19637.
---
 crates/oxc_parser/src/config.rs | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/crates/oxc_parser/src/config.rs b/crates/oxc_parser/src/config.rs
index e13b09eb5dfa3..ac70ce9dc3bec 100644
--- a/crates/oxc_parser/src/config.rs
+++ b/crates/oxc_parser/src/config.rs
@@ -32,8 +32,10 @@ use crate::lexer::{ByteHandler, ByteHandlers, byte_handler_tables};
 ///
 /// You can also create your own config by implementing [`ParserConfig`] on a type.
 pub trait ParserConfig: Default {
+    /// Type of [`LexerConfig`] this [`ParserConfig`] uses.
     type LexerConfig: LexerConfig;
 
+    /// Get [`LexerConfig`] for this [`ParserConfig`].
     fn lexer_config(&self) -> Self::LexerConfig;
 }
 
@@ -67,7 +69,7 @@ impl ParserConfig for TokensParserConfig {
     }
 }
 
-/// Parser config for parsing with/without tokens, decided at runtime.
+/// Parser config for parsing with / without tokens, decided at runtime.
 ///
 /// See [`ParserConfig`] for more details.
 #[derive(Copy, Clone, Default)]
@@ -93,11 +95,29 @@ impl ParserConfig for RuntimeParserConfig {
 }
 
 /// Lexer config.
+///
+/// See [`ParserConfig`] for more details.
+///
+/// We have to define a different byte handler table for each config, as byte handler functions
+/// are generic over the [`LexerConfig`].
+///
+/// Byte handler tables are defined within lexer (`lexer/byte_handlers.rs`).
+/// We need them to be defined as `static` items, for performance.
+/// 1. `static` ensures that only 1 copy of each byte handler table appears in the binary
+///    (even if `Lexer::handle_byte` is inlined in multiple places).
+/// 2. Indexing into byte handlers table is an extremely hot path, and even 1 extra indirection (pointer chasing)
+///    has a sizeable impact on performance.
+///
+/// An associated type and `byte_handlers` method is the only way to make this work with Rust's type system
+/// and borrow checker.
 pub trait LexerConfig: Default {
+    /// Byte handlers table type.
     type ByteHandlers: Index<usize, Output = ByteHandler<Self>>;
 
+    /// Returns `true` if tokens are enabled.
     fn tokens(&self) -> bool;
 
+    /// Get byte handlers table to use in lexer with this config.
     fn byte_handlers(&self) -> &Self::ByteHandlers;
 }
 
@@ -137,7 +157,7 @@ impl LexerConfig for TokensLexerConfig {
     }
 }
 
-/// Lexer config for lexing with/without tokens, decided at runtime.
+/// Lexer config for lexing with / without tokens, decided at runtime.
 #[derive(Copy, Clone, Default)]
 #[repr(transparent)]
 pub struct RuntimeLexerConfig {