docs(syntax): enable lint warnings on missing docs, and add a lot of …

…documentation (#6611)

Part of oxc-project/backlog#130

I didn't add doc comments to everything; I'm missing context for module-related data types and I have other things to do :P

crates/oxc_syntax/src/class.rs

@@ -1,3 +1,5 @@
+//! Class and class element syntax items
+#![allow(missing_docs)] // fixme
 use bitflags::bitflags;
 use oxc_index::define_index_type;
 

crates/oxc_syntax/src/identifier.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)] // fixme
 use assert_unchecked::assert_unchecked;
 use unicode_id_start::{is_id_continue_unicode, is_id_start_unicode};
 

crates/oxc_syntax/src/keyword.rs

@@ -1,10 +1,23 @@
+//! Keywords and reserved words in ECMAScript.
+//!
+//! ## References
+//! - [12.7.2 Keywords and Reserved Words](https://tc39.es/ecma262/#sec-keywords-and-reserved-words)
 use phf::{phf_set, Set};
 
+/// Checks if the given string is a [reserved keyword] or a [global object]
+/// (e.g. `NaN`).
+///
+/// [reserved keyword]: is_reserved_keyword
+/// [global object]: is_global_object
 #[inline]
 pub fn is_reserved_keyword_or_global_object(s: &str) -> bool {
     is_reserved_keyword(s) || is_global_object(s)
 }
 
+/// Checks if the given string is a reserved keyword.
+///
+/// Reserved keywords are either keywords currently used in the ECMAScript spec,
+/// or words that are reserved for future use.
 #[inline]
 pub fn is_reserved_keyword(s: &str) -> bool {
     RESERVED_KEYWORDS.contains(s)

crates/oxc_syntax/src/lib.rs

@@ -1,5 +1,5 @@
 //! Common code for JavaScript Syntax
-
+#![warn(missing_docs)]
 pub mod class;
 pub mod identifier;
 pub mod keyword;

crates/oxc_syntax/src/module_graph_visitor.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)] // fixme
 use std::{marker::PhantomData, path::PathBuf, sync::Arc};
 
 use oxc_span::CompactStr;

crates/oxc_syntax/src/module_record.rs

@@ -1,4 +1,5 @@
 //! [ECMAScript Module Record](https://tc39.es/ecma262/#sec-abstract-module-records)
+#![allow(missing_docs)] // fixme
 
 use std::{fmt, hash::BuildHasherDefault, path::PathBuf, sync::Arc};
 
@@ -302,14 +303,17 @@ pub enum ExportExportName {
 }
 
 impl ExportExportName {
+    /// Returns `true` if this is [`ExportExportName::Default`].
     pub fn is_default(&self) -> bool {
         matches!(self, Self::Default(_))
     }
 
+    /// Returns `true` if this is [`ExportExportName::Null`].
     pub fn is_null(&self) -> bool {
         matches!(self, Self::Null)
     }
 
+    /// Attempt to get the [`Span`] of this export name.
     pub fn span(&self) -> Option<Span> {
         match self {
             Self::Name(name) => Some(name.span()),
@@ -330,14 +334,17 @@ pub enum ExportLocalName {
 }
 
 impl ExportLocalName {
+    /// `true` if this is a [`ExportLocalName::Default`].
     pub fn is_default(&self) -> bool {
         matches!(self, Self::Default(_))
     }
 
+    /// `true` if this is a [`ExportLocalName::Null`].
     pub fn is_null(&self) -> bool {
         matches!(self, Self::Null)
     }
 
+    /// Get the bound name of this export. [`None`] for [`ExportLocalName::Null`].
     pub const fn name(&self) -> Option<&CompactStr> {
         match self {
             Self::Name(name) | Self::Default(name) => Some(name.name()),
@@ -367,10 +374,19 @@ impl RequestedModule {
         self.span
     }
 
+    /// `true` if a `type` modifier was used in the import statement.
+    ///
+    /// ## Examples
+    /// ```ts
+    /// import type { foo } from "foo"; // true, `type` is on module request
+    /// import { type bar } from "bar"; // false, `type` is on specifier
+    /// import { baz } from "baz";      // false, no `type` modifier
+    /// ```
     pub fn is_type(&self) -> bool {
         self.is_type
     }
 
+    /// `true` if the module is requested by an import statement.
     pub fn is_import(&self) -> bool {
         self.is_import
     }

crates/oxc_syntax/src/node.rs

@@ -1,3 +1,4 @@
+//! AST Node ID and flags.
 use bitflags::bitflags;
 use nonmax::NonMaxU32;
 use oxc_index::Idx;
@@ -9,6 +10,9 @@ use serde::{Serialize, Serializer};
 pub struct NodeId(NonMaxU32);
 
 impl NodeId {
+    /// Mock node id.
+    ///
+    /// This is used for synthetically-created AST nodes, among other things.
     pub const DUMMY: Self = NodeId::new(0);
 
     /// Create `NodeId` from `u32`.
@@ -69,11 +73,15 @@ export type NodeFlags = {
 "#;
 
 bitflags! {
+    /// Contains additional information about an AST node.
     #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
     pub struct NodeFlags: u8 {
-        const JSDoc     = 1 << 0; // If the Node has a JSDoc comment attached
-        const Class     = 1 << 1; // If Node is inside a class
-        const HasYield  = 1 << 2; // If function has yield statement
+        /// Set if the Node has a JSDoc comment attached
+        const JSDoc     = 1 << 0;
+        /// Set on Nodes inside classes
+        const Class     = 1 << 1;
+        /// Set functions containing yield statements
+        const HasYield  = 1 << 2;
     }
 }
 

crates/oxc_syntax/src/number.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)] // fixme
 use oxc_allocator::CloneIn;
 use oxc_ast_macros::ast;
 use oxc_span::{cmp::ContentEq, hash::ContentHash};