chore: clean up docs and remove some pub fields

Author: Boshen

examples/resolver.rs

@@ -1,30 +1,24 @@
-// Instruction:
-//
-// run `cargo run --example resolver -- `pwd` test.js`
-// or `cargo watch -x "run --example resolver" -- `pwd` test.js`
-//
-// NOTE: The first argument must be a absolute path.
-
 use std::{env, path::PathBuf};
 
 use oxc_resolver::{AliasValue, ResolveOptions, Resolver};
 
 fn main() {
-    let path = env::args().nth(1).expect("require path");
-    let request = env::args().nth(2).expect("require request");
+    // Path to directory, must be in absolute path.
+    let path = env::args().nth(1).expect("path");
+    let specifier = env::args().nth(2).expect("specifier");
     let path = PathBuf::from(path).canonicalize().unwrap();
 
     println!("path: {path:?}");
-    println!("request: {request}");
+    println!("request: {specifier}");
 
     let options = ResolveOptions {
         alias_fields: vec![vec!["browser".into()]],
-        alias: vec![("/asdf".into(), vec![AliasValue::Path("./test.js".into())])],
+        alias: vec![("asdf".into(), vec![AliasValue::Path("./test.js".into())])],
         ..ResolveOptions::default()
     };
 
-    match Resolver::new(options).resolve(path, &request) {
+    match Resolver::new(options).resolve(path, &specifier) {
         Err(error) => println!("Error: {error}"),
-        Ok(resolution) => println!("Resolved: {}", resolution.full_path().to_string_lossy()),
+        Ok(resolution) => println!("Resolved: {:?}", resolution.full_path()),
     }
 }

src/error.rs

@@ -1,7 +1,9 @@
 use std::{io, path::PathBuf, sync::Arc};
 use thiserror::Error;
 
-/// All resolution errors.
+/// All resolution errors
+///
+/// `thiserror` is used to display meaningful error messages.
 #[derive(Debug, Clone, PartialEq, Error)]
 pub enum ResolveError {
     /// Ignored path
@@ -96,13 +98,14 @@ impl ResolveError {
     }
 }
 
+/// Error for [ResolveError::Specifier]
 #[derive(Debug, Clone, Eq, PartialEq, Error)]
 pub enum SpecifierError {
-    #[error("[ERR_INVALID_ARG_VALUE]: The specifiers must be a non-empty string. Received ''")]
+    #[error("The specifiers must be a non-empty string. Received ''")]
     Empty,
 }
 
-/// JSON error from [serde_json::Error].
+/// JSON error from [serde_json::Error]
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct JSONError {
     pub path: PathBuf,

src/file_system.rs

@@ -53,7 +53,7 @@ pub trait FileSystem: Send + Sync {
     fn canonicalize(&self, path: &Path) -> io::Result<PathBuf>;
 }
 
-/// Metadata information about a file.
+/// Metadata information about a file
 #[derive(Debug, Clone, Copy)]
 pub struct FileMetadata {
     pub(crate) is_file: bool,

src/lib.rs

@@ -2,18 +2,24 @@
 //!
 //! Node.js Module Resolution.
 //!
-//! All configuration options are aligned with [enhanced-resolve]
+//! All configuration options are aligned with [enhanced-resolve].
 //!
 //! ## References:
 //!
-//! * Tests ported from [enhanced-resolve]
 //! * Algorithm adapted from Node.js [CommonJS Module Resolution Algorithm] and [ECMAScript Module Resolution Algorithm]
+//! * Tests are ported from [enhanced-resolve]
 //! * Some code adapted from [parcel-resolver]
 //!
 //! [enhanced-resolve]: https://github.com/webpack/enhanced-resolve
 //! [CommonJS Module Resolution Algorithm]: https://nodejs.org/api/modules.html#all-together
 //! [ECMAScript Module Resolution Algorithm]: https://nodejs.org/api/esm.html#resolution-algorithm-specification
 //! [parcel-resolver]: https://github.com/parcel-bundler/parcel/blob/v2/packages/utils/node-resolver-rs
+//!
+//! ## Example
+//!
+//! ```rust
+#![doc = include_str!("../examples/resolver.rs")]
+//! ```
 
 mod builtins;
 mod cache;
@@ -63,7 +69,7 @@ pub use crate::{
 /// Resolver with the current operating system as the file system
 pub type Resolver = ResolverGeneric<FileSystemOs>;
 
-/// Generic implementation of the resolver, can be configured by the [FileSystem] trait.
+/// Generic implementation of the resolver, can be configured by the [FileSystem] trait
 pub struct ResolverGeneric<Fs> {
     options: ResolveOptions,
     cache: Arc<Cache<Fs>>,
@@ -153,10 +159,12 @@ impl<Fs: FileSystem + Default> ResolverGeneric<Fs> {
         Self { options: options.sanitize(), cache: Arc::clone(&self.cache) }
     }
 
+    /// Returns the options.
     pub fn options(&self) -> &ResolveOptions {
         &self.options
     }
 
+    /// Clear the underlying cache.
     pub fn clear_cache(&self) {
         self.cache.clear();
     }

src/options.rs

@@ -130,6 +130,7 @@ pub struct ResolveOptions {
     pub builtin_modules: bool,
 }
 
+/// Value for [ResolveOptions::enforce_extension]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum EnforceExtension {
     Auto,
@@ -164,13 +165,14 @@ pub enum AliasValue {
     Ignore,
 }
 
+/// Value for [ResolveOptions::restrictions]
 #[derive(Debug, Clone)]
 pub enum Restriction {
     Path(PathBuf),
     RegExp(String),
 }
 
-/// Tsconfig Options
+/// Tsconfig Options for [ResolveOptions::tsconfig]
 ///
 /// Derived from [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin#options)
 #[derive(Debug, Clone)]
@@ -185,6 +187,7 @@ pub struct TsconfigOptions {
     pub references: TsconfigReferences,
 }
 
+/// Configuration for [TsconfigOptions::references]
 #[derive(Debug, Clone)]
 pub enum TsconfigReferences {
     Disabled,

src/package_json.rs

@@ -15,25 +15,25 @@ use crate::{path::PathUtil, ResolveError, ResolveOptions};
 
 type FxIndexMap<K, V> = IndexMap<K, V, BuildHasherDefault<FxHasher>>;
 
+/// Deserialized package.json
 #[derive(Debug, Deserialize)]
 pub struct PackageJson {
     /// Path to `package.json`. Contains the `package.json` filename.
     #[serde(skip)]
-    pub path: PathBuf,
+    pub(crate) path: PathBuf,
 
     /// Realpath to `package.json`. Contains the `package.json` filename.
     #[serde(skip)]
-    pub realpath: PathBuf,
+    pub(crate) realpath: PathBuf,
 
     #[serde(skip)]
-    #[serde(default)]
-    pub raw_json: Arc<serde_json::Value>,
+    pub(crate) raw_json: Arc<serde_json::Value>,
 
     /// The "name" field defines your package's name.
     /// The "name" field can be used in addition to the "exports" field to self-reference a package using its name.
     ///
     /// <https://nodejs.org/api/packages.html#name>
-    pub name: Option<String>,
+    pub(crate) name: Option<String>,
 
     /// The "main" field defines the entry point of a package when imported by name via a node_modules lookup. Its value is a path.
     /// When a package has an "exports" field, this will take precedence over the "main" field when importing the package by name.
@@ -42,26 +42,26 @@ pub struct PackageJson {
     ///
     /// <https://nodejs.org/api/packages.html#main>
     #[serde(skip)]
-    pub main_fields: Vec<String>,
+    pub(crate) main_fields: Vec<String>,
 
     /// The "exports" field allows defining the entry points of a package when imported by name loaded either via a node_modules lookup or a self-reference to its own name.
     ///
     /// <https://nodejs.org/api/packages.html#exports>
     #[serde(skip)]
-    pub exports: Vec<ExportsField>,
+    pub(crate) exports: Vec<ExportsField>,
 
     /// In addition to the "exports" field, there is a package "imports" field to create private mappings that only apply to import specifiers from within the package itself.
     ///
     /// <https://nodejs.org/api/packages.html#subpath-imports>
     #[serde(default)]
-    pub imports: Box<MatchObject>,
+    pub(crate) imports: Box<MatchObject>,
 
     /// The "browser" field is provided by a module author as a hint to javascript bundlers or component tools when packaging modules for client side use.
     /// Multiple values are configured by [ResolveOptions::alias_fields].
     ///
     /// <https://github.com/defunctzombie/package-browser-field-spec>
     #[serde(skip)]
-    pub browser_fields: Vec<BrowserField>,
+    pub(crate) browser_fields: Vec<BrowserField>,
 }
 
 /// `matchObj` defined in `PACKAGE_IMPORTS_EXPORTS_RESOLVE`
@@ -119,7 +119,7 @@ pub enum BrowserField {
 impl PackageJson {
     /// # Panics
     /// # Errors
-    pub fn parse(
+    pub(crate) fn parse(
         path: PathBuf,
         realpath: PathBuf,
         json: &str,
@@ -241,7 +241,7 @@ impl PackageJson {
     /// # Errors
     ///
     /// * Returns [ResolveError::Ignored] for `"path": false` in `browser` field.
-    pub fn resolve_browser_field(
+    pub(crate) fn resolve_browser_field(
         &self,
         path: &Path,
         request: Option<&str>,

src/resolution.rs

@@ -5,7 +5,7 @@ use std::{
     sync::Arc,
 };
 
-/// The final path resolution with optional `?query` and `#fragment`.
+/// The final path resolution with optional `?query` and `#fragment`
 #[derive(Clone)]
 pub struct Resolution {
     pub(crate) path: PathBuf,
@@ -58,6 +58,7 @@ impl Resolution {
         self.fragment.as_deref()
     }
 
+    /// Returns serialized package_json
     pub fn package_json(&self) -> Option<&Arc<PackageJson>> {
         self.package_json.as_ref()
     }