chore(resolver): improve documentation (#591)

crates/oxc_resolver/README.md

@@ -3,7 +3,6 @@
 ## TODO
 
 - [ ] use `thiserror` for better error messages
-- [ ] copy API documentation from webpack https://webpack.js.org/configuration/resolve/#resolve
 
 #### Resolver Options
 
@@ -38,9 +37,10 @@
 ## Test
 
 Tests ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve).
+Crossed out test files are irrelevant.
 
-- [ ] CachedInputFileSystem.test.js
-- [ ] SyncAsyncFileSystemDecorator.test.js
+- [x] ~CachedInputFileSystem.test.js~
+- [x] ~SyncAsyncFileSystemDecorator.test.js~
 - [x] alias.test.js (need to fix a todo)
 - [x] browserField.test.js (reading the browser field is currently static - not read from the `browserField` option)
 - [ ] dependencies.test.js
@@ -48,7 +48,7 @@ Tests ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve
 - [x] extension-alias.test.js
 - [x] extensions.test.js
 - [x] fallback.test.js (need to fix a todo)
-- ~[ ] forEachBail.test.js~
+- [x] ~forEachBail.test.js~
 - [ ] fullSpecified.test.js
 - [ ] getPaths.test.js
 - [x] identifier.test.js (see unit test in `crates/oxc_resolver/src/request.rs`)
@@ -58,12 +58,12 @@ Tests ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve
 - [ ] path.test.js
 - [ ] plugins.test.js
 - [ ] pnp.test.js
-- [ ] pr-53.test.js
+- [x] ~pr-53.test.js~
 - [x] resolve.test.js (need to add resolveToContext)
 - [ ] restrictions.test.js
 - [x] roots.test.js (need to add resolveToContext)
 - [x] scoped-packages.test.js
 - [x] simple.test.js
 - [x] symlink.test.js
-- [ ] unsafe-cache.test.js
-- [ ] yield.test.js
+- [x] ~unsafe-cache.test.js~
+- [x] ~yield.test.js~

crates/oxc_resolver/src/cache.rs

@@ -48,7 +48,7 @@ impl<Fs: FileSystem> Cache<Fs> {
     ///
     /// # Errors
     ///
-    /// * [ResolveError::JSONError]
+    /// * [ResolveError::JSON]
     pub fn get_package_json(&self, path: &Path) -> Result<Option<Arc<PackageJson>>, ResolveError> {
         self.cache_value(path).package_json(&self.fs).transpose()
     }
@@ -57,7 +57,7 @@ impl<Fs: FileSystem> Cache<Fs> {
     ///
     /// # Errors
     ///
-    /// * [ResolveError::JSONError]
+    /// * [ResolveError::JSON]
     pub fn find_package_json(&self, path: &Path) -> Result<Option<Arc<PackageJson>>, ResolveError> {
         let mut cache_value = Some(self.cache_value(path));
         while let Some(cv) = cache_value {

crates/oxc_resolver/src/lib.rs

@@ -1,5 +1,7 @@
 //! # Oxc Resolver
 //!
+//! Node.js Module Resolution.
+//!
 //! ## References:
 //!
 //! * Tests ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve)
@@ -21,25 +23,26 @@ use std::{
     path::{Path, PathBuf},
 };
 
-pub use crate::{
-    cache::Cache,
-    error::{JSONError, ResolveError},
-    file_system::{FileMetadata, FileSystem, FileSystemOs},
-    options::{Alias, AliasValue, ResolveOptions},
-    resolution::Resolution,
-};
 use crate::{
+    cache::Cache,
+    file_system::FileSystemOs,
     package_json::PackageJson,
     path::PathUtil,
     request::{Request, RequestPath},
 };
+pub use crate::{
+    error::{JSONError, ResolveError},
+    file_system::{FileMetadata, FileSystem},
+    options::{Alias, AliasValue, ResolveOptions},
+    resolution::Resolution,
+};
 
-pub type ResolveResult = Result<Resolution, ResolveError>;
 type ResolveState = Result<Option<PathBuf>, ResolveError>;
 
 /// Resolver with the current operating system as the file system
 pub type Resolver = ResolverGeneric<FileSystemOs>;
 
+/// Generic implementation of the resolver, backed by a cached file system.
 pub struct ResolverGeneric<Fs> {
     options: ResolveOptions,
     cache: Cache<Fs>,

crates/oxc_resolver/src/options.rs

@@ -11,9 +11,15 @@ pub enum AliasValue {
     Ignore,
 }
 
+/// Module Resolution Options
+///
+/// Options are directly ported from [enhanced-resolve](https://github.com/webpack/enhanced-resolve#resolver-options).
+///
+/// See [webpack resolve](https://webpack.js.org/configuration/resolve/) for information and examples
 #[derive(Debug, Clone)]
 pub struct ResolveOptions {
-    /// A list of module alias configurations or an object which maps key to value
+    /// Create aliases to import or require certain modules more easily.
+    /// A trailing $ can also be added to the given object's keys to signify an exact match.
     pub alias: Alias,
 
     /// A list of alias fields in description files.
@@ -22,12 +28,14 @@ pub struct ResolveOptions {
     /// Default `[]`
     pub alias_fields: Vec<String>,
 
-    /// A list of description files to read (there was once a `bower.json`).
+    /// The JSON files to use for descriptions. (There was once a `bower.json`.)
     ///
     /// Default `["package.json"]`
     pub description_files: Vec<String>,
 
-    /// Enforce that a extension from extensions must be used.
+    /// If true, it will not allow extension-less files.
+    /// So by default `require('./foo')` works if `./foo` has a `.js` extension,
+    /// but with this enabled only `require('./foo.js')` will work.
     ///
     /// Default to `true` when [ResolveOptions::extensions] contains an empty string.
     /// Use `Some(false)` to disable the behavior.
@@ -41,17 +49,19 @@ pub struct ResolveOptions {
     /// Default `{}`
     pub extension_alias: Vec<(String, Vec<String>)>,
 
-    /// A list of extensions which should be tried for.
+    /// Attempt to resolve these extensions in order.
+    /// If multiple files share the same name but have different extensions,
+    /// will resolve the one with the extension listed first in the array and skip the rest.
     ///
     /// Default `[".js", ".json", ".node"]`
     pub extensions: Vec<String>,
 
-    /// Same as [ResolveOptions::alias], Redirect module requests when normal resolving fails. .
+    /// Redirect module requests when normal resolving fails.
     ///
     /// Default `[]`
     pub fallback: Alias,
 
-    /// A list of main files in directories.
+    /// The filename to be used while resolving directories.
     ///
     /// Default `["index"]`
     pub main_files: Vec<String>,
@@ -61,7 +71,7 @@ pub struct ResolveOptions {
     /// Default `["node_modules"]`
     pub modules: Vec<String>,
 
-    /// prefer to resolve module requests as relative requests instead of using modules from node_modules directories.
+    /// Prefer to resolve module requests as relative requests instead of using modules from node_modules directories.
     ///
     /// Default `false`
     pub prefer_relative: bool,

crates/oxc_resolver/src/path.rs

@@ -2,7 +2,7 @@
 //!
 //! Code adapted from the following libraries
 //! * [path-absolutize](https://docs.rs/path-absolutize)
-//! * [normalize_path](<https://docs.rs/normalize-path)
+//! * [normalize_path](https://docs.rs/normalize-path)
 use std::path::{Component, Path, PathBuf};
 
 /// Extension trait to add path normalization to std's [`Path`].