fix(rust): fix missing docs (#13541)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: Boshen

.claude/settings.local.json

@@ -3,7 +3,10 @@
     "allow": [
       "Bash(find:*)",
       "Bash(cargo check:*)",
-      "Bash(cargo clippy:*)"
+      "Bash(ast-grep:*)",
+      "Bash(rg:*)",
+      "Bash(cargo clippy:*)",
+      "Bash(cargo build:*)"
     ],
     "deny": [],
     "ask": []

crates/oxc_ast/src/ast/js.rs

@@ -1,5 +1,17 @@
+//! JavaScript AST node definitions
+//!
+//! This module contains the core AST node definitions for JavaScript syntax including:
+//! - Program structure and statements
+//! - Expressions and literals
+//! - Functions and classes
+//! - Patterns and identifiers
+//! - Module declarations (import/export)
+//! - JSX syntax support
+//!
+//! The AST design follows ECMAScript specifications while providing
+//! clear distinctions between different identifier types for better type safety.
 #![expect(
-    missing_docs, // FIXME
+    missing_docs, // TODO: document individual struct fields
     clippy::enum_variant_names,
     clippy::struct_field_names,
 )]

crates/oxc_ast/src/ast/ts.rs

@@ -1,9 +1,17 @@
 //! TypeScript Definitions
 //!
+//! This module contains AST node definitions for TypeScript syntax including:
+//! - Type annotations and declarations
+//! - Interfaces and type aliases
+//! - Enums and namespaces
+//! - TypeScript-specific expressions
+//! - Import/export extensions
+//!
+//! ## References
 //! - [AST Spec](https://github.com/typescript-eslint/typescript-eslint/tree/v8.9.0/packages/ast-spec)
 //! - [Archived TypeScript spec](https://github.com/microsoft/TypeScript/blob/3c99d50da5a579d9fa92d02664b1b66d4ff55944/doc/spec-ARCHIVED.md)
 #![expect(
-    missing_docs, // FIXME
+    missing_docs, // TODO: document individual struct fields  
     clippy::enum_variant_names,
 )]
 

crates/oxc_ast/src/ast_kind_impl.rs

@@ -1,11 +1,18 @@
-#![expect(missing_docs)] // FIXME
+//! Implementation details for AST node kinds
+//!
+//! This module provides methods and utilities for working with [`AstKind`],
+//! including type checking, conversions, and tree traversal helpers.
 
 use oxc_allocator::{Address, GetAddress};
 use oxc_span::{Atom, GetSpan};
 
 use super::{AstKind, ast::*};
 
 impl<'a> AstKind<'a> {
+    /// Check if this AST node is a statement
+    ///
+    /// Returns `true` for all statement types including iteration statements,
+    /// control flow statements, and declaration statements.
     #[rustfmt::skip]
     pub fn is_statement(self) -> bool {
         self.is_iteration_statement()
@@ -16,6 +23,10 @@ impl<'a> AstKind<'a> {
                     | Self::IfStatement(_) | Self::VariableDeclaration(_) | Self::ExportDefaultDeclaration(_))
     }
 
+    /// Check if this AST node is a declaration
+    ///
+    /// Returns `true` for function declarations, class declarations,
+    /// variable declarations, TypeScript declarations, and module declarations.
     #[rustfmt::skip]
     pub fn is_declaration(self) -> bool {
         matches!(self, Self::Function(func) if func.is_declaration())
@@ -26,10 +37,17 @@ impl<'a> AstKind<'a> {
         ) || self.is_module_declaration()
     }
 
+    /// Check if this AST node is a module declaration
+    ///
+    /// Returns `true` for import/export declarations.
     pub fn is_module_declaration(self) -> bool {
         self.as_module_declaration_kind().is_some()
     }
 
+    /// Attempt to convert this AST node to a module declaration kind
+    ///
+    /// Returns `Some(ModuleDeclarationKind)` if this is a module declaration,
+    /// `None` otherwise.
     pub fn as_module_declaration_kind(&self) -> Option<ModuleDeclarationKind<'a>> {
         match self {
             Self::ImportDeclaration(decl) => Some(ModuleDeclarationKind::Import(decl)),
@@ -46,19 +64,30 @@ impl<'a> AstKind<'a> {
         }
     }
 
+    /// Check if this AST node is an iteration statement
+    ///
+    /// Returns `true` for do-while, while, for-in, for-of, and for statements.
     #[rustfmt::skip]
     pub fn is_iteration_statement(self) -> bool {
         matches!(self, Self::DoWhileStatement(_) | Self::WhileStatement(_) | Self::ForInStatement(_)
                 | Self::ForOfStatement(_) | Self::ForStatement(_))
     }
 
+    /// Check if this AST node is any kind of identifier
+    ///
+    /// Returns `true` for binding identifiers, identifier references,
+    /// and label identifiers.
     #[rustfmt::skip]
     pub fn is_identifier(self) -> bool {
         matches!(self, Self::BindingIdentifier(_)
                 | Self::IdentifierReference(_)
                 | Self::LabelIdentifier(_))
     }
 
+    /// Check if this AST node is a TypeScript type
+    ///
+    /// Returns `true` for all TypeScript type nodes including keywords,
+    /// type references, unions, intersections, etc.
     #[rustfmt::skip]
     pub fn is_type(self) -> bool {
         matches!(self, Self::TSAnyKeyword(_) | Self::TSBigIntKeyword(_) | Self::TSBooleanKeyword(_) | Self::TSIntrinsicKeyword(_)
@@ -69,6 +98,10 @@ impl<'a> AstKind<'a> {
                 | Self::TSTypeLiteral(_) | Self::TSTypeReference(_) | Self::TSUnionType(_))
     }
 
+    /// Check if this AST node is a literal
+    ///
+    /// Returns `true` for numeric, string, boolean, null, bigint,
+    /// regexp, and template literals.
     pub fn is_literal(self) -> bool {
         matches!(
             self,
@@ -82,10 +115,17 @@ impl<'a> AstKind<'a> {
         )
     }
 
+    /// Check if this AST node is function-like
+    ///
+    /// Returns `true` for function expressions/declarations and arrow functions.
     pub fn is_function_like(self) -> bool {
         matches!(self, Self::Function(_) | Self::ArrowFunctionExpression(_))
     }
 
+    /// Get the name of an identifier node
+    ///
+    /// Returns the identifier name if this is any kind of identifier node,
+    /// `None` otherwise.
     pub fn identifier_name(self) -> Option<Atom<'a>> {
         match self {
             Self::BindingIdentifier(ident) => Some(ident.name),
@@ -96,6 +136,9 @@ impl<'a> AstKind<'a> {
         }
     }
 
+    /// Check if this is an identifier reference with a specific name
+    ///
+    /// Returns `true` if this is an `IdentifierReference` with the given name.
     pub fn is_specific_id_reference(&self, name: &str) -> bool {
         match self {
             Self::IdentifierReference(ident) => ident.name == name,
@@ -125,10 +168,17 @@ impl<'a> AstKind<'a> {
         }
     }
 
+    /// Check if this AST node is a property key
+    ///
+    /// Returns `true` for identifier names and private identifiers used as property keys.
     pub fn is_property_key(&self) -> bool {
         self.as_property_key_kind().is_some()
     }
 
+    /// Attempt to convert this AST node to a property key kind
+    ///
+    /// Returns `Some(PropertyKeyKind)` if this is a property key,
+    /// `None` otherwise.
     pub fn as_property_key_kind(&self) -> Option<PropertyKeyKind<'a>> {
         match self {
             Self::IdentifierName(ident) => Some(PropertyKeyKind::Static(ident)),
@@ -137,6 +187,9 @@ impl<'a> AstKind<'a> {
         }
     }
 
+    /// Create an `AstKind` from an expression
+    ///
+    /// Converts any expression type to its corresponding `AstKind` variant.
     pub fn from_expression(e: &'a Expression<'a>) -> Self {
         match e {
             Expression::BooleanLiteral(e) => Self::BooleanLiteral(e),
@@ -649,12 +702,21 @@ impl GetAddress for MemberExpressionKind<'_> {
     }
 }
 
+/// Module declaration types
+///
+/// Represents different kinds of module import and export declarations.
 pub enum ModuleDeclarationKind<'a> {
+    /// An import declaration like `import foo from 'bar'`
     Import(&'a ImportDeclaration<'a>),
+    /// An export all declaration like `export * from 'foo'`
     ExportAll(&'a ExportAllDeclaration<'a>),
+    /// A named export declaration like `export { foo, bar }`
     ExportNamed(&'a ExportNamedDeclaration<'a>),
+    /// A default export declaration like `export default foo`
     ExportDefault(&'a ExportDefaultDeclaration<'a>),
+    /// A TypeScript export assignment like `export = foo`
     TSExportAssignment(&'a TSExportAssignment<'a>),
+    /// A TypeScript namespace export like `export as namespace foo`
     TSNamespaceExport(&'a TSNamespaceExportDeclaration<'a>),
 }
 
@@ -685,6 +747,9 @@ impl GetSpan for ModuleDeclarationKind<'_> {
     }
 }
 
+/// Property key types
+///
+/// Represents different kinds of property keys in objects and classes.
 pub enum PropertyKeyKind<'a> {
     /// A static identifier property key, like `a` in `{ a: 1 }`.
     Static(&'a IdentifierName<'a>),

crates/oxc_ast/src/trivia.rs

@@ -1,5 +1,7 @@
 //! Trivia such as comments and irregular whitespaces
-#![expect(missing_docs)] // FIXME
+//!
+//! This module provides utilities for working with source code comments,
+//! including efficient range-based queries and iteration over comment collections.
 
 use std::{
     iter::FusedIterator,
@@ -10,18 +12,59 @@ use oxc_span::Span;
 
 use crate::ast::comment::*;
 
+/// Create an iterator over comments within a given range
+///
+/// Returns a double-ended iterator that yields comments whose starting positions
+/// fall within the specified range bounds.
+///
+/// # Arguments
+///
+/// * `comments` - A slice of comments sorted by starting position
+/// * `range` - The range of positions to filter comments by
+///
+/// # Examples
+///
+/// ```ignore
+/// let comments_in_range = comments_range(&all_comments, 10..50);
+/// for comment in comments_in_range {
+///     // Process comments starting between positions 10 and 50
+/// }
+/// ```
 pub fn comments_range<R>(comments: &[Comment], range: R) -> CommentsRange<'_>
 where
     R: RangeBounds<u32>,
 {
     CommentsRange::new(comments, range.start_bound().cloned(), range.end_bound().cloned())
 }
 
+/// Check if there are any comments within a given span
+///
+/// Returns `true` if at least one comment starts within the specified span.
+///
+/// # Arguments
+///
+/// * `comments` - A slice of comments sorted by starting position
+/// * `span` - The span to check for comments
+///
+/// # Examples
+///
+/// ```ignore
+/// if has_comments_between(&comments, node.span) {
+///     // Handle nodes that have comments within their span
+/// }
+/// ```
 pub fn has_comments_between(comments: &[Comment], span: Span) -> bool {
     comments_range(comments, span.start..span.end).count() > 0
 }
 
-/// Double-ended iterator over a range of comments, by starting position.
+/// Double-ended iterator over a range of comments, by starting position
+///
+/// This iterator efficiently filters comments based on their starting positions,
+/// using binary search to skip comments outside the range. It supports both
+/// forward and backward iteration.
+///
+/// The iterator is created using [`comments_range`] and yields references to
+/// comments whose `span.start` falls within the specified range bounds.
 pub struct CommentsRange<'c> {
     comments: &'c [Comment],
     range: (Bound<u32>, Bound<u32>),
@@ -30,6 +73,10 @@ pub struct CommentsRange<'c> {
 }
 
 impl<'c> CommentsRange<'c> {
+    /// Create a new iterator over comments in the specified range
+    ///
+    /// Uses `partition_point` to efficiently skip comments outside the range,
+    /// avoiding unnecessary iteration over comments that won't be yielded.
     fn new(comments: &'c [Comment], start: Bound<u32>, end: Bound<u32>) -> Self {
         // Directly skip all comments that are already known to start
         // outside the requested range.

crates/oxc_codegen/src/context.rs

@@ -1,47 +1,70 @@
-#![expect(missing_docs)] // FIXME
+//! Code generation context management
+//!
+//! This module provides the [`Context`] type for managing the state and configuration
+//! during code generation, including JavaScript/TypeScript-specific syntax rules.
 
 use bitflags::bitflags;
 
 bitflags! {
+    /// Code generation context flags
+    ///
+    /// Controls various aspects of code generation including operator precedence,
+    /// language features, and syntax restrictions.
     #[derive(Debug, Default, Clone, Copy)]
     pub struct Context: u8 {
-        /// [In]
+        /// Forbid the `in` operator in expressions
+        ///
+        /// Used in contexts where the `in` operator could be ambiguous,
+        /// such as in the init clause of a for loop.
         const FORBID_IN   = 1 << 0;
+        /// Forbid call expressions
+        ///
+        /// Used to prevent ambiguity in contexts like new expressions
+        /// where parentheses could be interpreted differently.
         const FORBID_CALL = 1 << 1;
+        /// Enable TypeScript-specific code generation
+        ///
+        /// When set, TypeScript syntax features are enabled in the output.
         const TYPESCRIPT  = 1 << 2;
     }
 }
 
 impl Context {
+    /// Check if the `in` operator is forbidden in the current context
     #[inline]
     pub fn forbid_in(self) -> bool {
         self.contains(Self::FORBID_IN)
     }
 
+    /// Check if call expressions are forbidden in the current context
     #[inline]
     pub fn forbid_call(self) -> bool {
         self.contains(Self::FORBID_CALL)
     }
 
+    /// Create a new context with TypeScript support enabled
     #[inline]
     #[must_use]
     pub fn with_typescript(mut self) -> Self {
         self |= Self::TYPESCRIPT;
         self
     }
 
+    /// Conditionally set or unset the `FORBID_IN` flag
     #[inline]
     #[must_use]
     pub fn and_forbid_in(self, include: bool) -> Self {
         self.and(Self::FORBID_IN, include)
     }
 
+    /// Conditionally set or unset the `FORBID_CALL` flag
     #[inline]
     #[must_use]
     pub fn and_forbid_call(self, include: bool) -> Self {
         self.and(Self::FORBID_CALL, include)
     }
 
+    /// Helper method to conditionally set or unset a flag
     #[inline]
     fn and(self, flag: Self, set: bool) -> Self {
         if set { self | flag } else { self - flag }