doc(fs): improve glob documentation formatting per review feedback

Author: mag123c

doc/api/fs.md

@@ -1101,99 +1101,167 @@ changes:
 * Returns: {AsyncIterator} An AsyncIterator that yields the paths of files
   that match the pattern.
 
-Retrieves the files matching the specified pattern(s).
+Retrieves the file paths matching the specified pattern(s).
 
 #### Pattern Syntax
 
 The glob implementation supports the following pattern syntax:
 
 **Basic Wildcards:**
-* `*` - Matches any number of characters within a single path segment
-* `?` - Matches exactly one character
-* `[abc]` - Matches any character in the brackets
-* `[a-z]` - Matches any character in the range
-* `[!abc]` or `[^abc]` - Matches any character not in the brackets
-* `[!a-z]` or `[^a-z]` - Matches any character not in the range
+
+| Pattern | Description |
+| ------- | ----------- |
+| `*` | Matches any number of characters within a single path segment. |
+| `?` | Matches exactly one character. |
+| `[abc]` | Matches any character in the brackets. |
+| `[a-z]` | Matches any character in the range. |
+| `[!abc]` or `[^abc]` | Matches any character not in the brackets. |
+| `[!a-z]` or `[^a-z]` | Matches any character not in the range. |
 
 **Globstar:**
-* `**` - Matches zero or more directories recursively
-* `**/*.js` - Matches all `.js` files in any subdirectory
+
+| Pattern | Description |
+| ------- | ----------- |
+| `**` | Matches zero or more directories recursively. |
+| `**/*.js` | Matches all `.js` files in any subdirectory. |
 
 **Brace Expansion:**
-* `{a,b,c}` - Matches any of the comma-separated patterns
-* `{1..5}` - Matches any number in the range (1, 2, 3, 4, 5)
-* `*.{js,ts}` - Matches files with `.js` or `.ts` extensions
+
+| Pattern | Description |
+| ------- | ----------- |
+| `{a,b,c}` | Matches any of the comma-separated patterns. |
+| `{1..5}` | Matches any number in the range (1, 2, 3, 4, 5). |
+| `*.{js,ts}` | Matches files with `.js` or `.ts` extensions. |
 
 **Extended Glob Patterns:**
-* `+(pattern)` - Matches one or more occurrences of the pattern
-* `*(pattern)` - Matches zero or more occurrences of the pattern
-* `?(pattern)` - Matches zero or one occurrence of the pattern
-* `!(pattern)` - Matches anything except the pattern
+
+| Pattern | Description |
+| ------- | ----------- |
+| `+(pattern)` | Matches one or more occurrences of the pattern. |
+| `*(pattern)` | Matches zero or more occurrences of the pattern. |
+| `?(pattern)` | Matches zero or one occurrence of the pattern. |
+| `!(pattern)` | Matches anything except the pattern. |
 
 #### Examples
 
+The following examples demonstrate common glob usage patterns.
+
+**Basic pattern matching:**
+
+Match all `.js` files in the current directory.
+
 ```mjs
 import { glob } from 'node:fs/promises';
 
-// Basic patterns
 for await (const entry of glob('*.js'))
-  console.log(entry); // All .js files in current directory
+  console.log(entry);
+```
+
+```cjs
+const { glob } = require('node:fs/promises');
+
+(async () => {
+  for await (const entry of glob('*.js'))
+    console.log(entry);
+})();
+```
+
+**Recursive search with brace expansion:**
+
+Match all `.js` and `.ts` files in any subdirectory.
+
+```mjs
+import { glob } from 'node:fs/promises';
 
-// Recursive search
 for await (const entry of glob('**/*.{js,ts}'))
-  console.log(entry); // All .js and .ts files in any subdirectory
+  console.log(entry);
+```
+
+**Using `Array.fromAsync` to collect results:**
+
+Convert the async iterator to an array for easier manipulation.
+
+```mjs
+import { glob } from 'node:fs/promises';
+
+const files = await Array.fromAsync(glob('src/**/*.js'));
+console.log(files);
+```
+
+**Brace expansion for multiple directories:**
+
+Match `.js` files in `src/components` or `src/utils` directories.
+
+```mjs
+import { glob } from 'node:fs/promises';
 
-// Brace expansion
 for await (const entry of glob('src/{components,utils}/**/*.js'))
-  console.log(entry); // .js files in src/components or src/utils
+  console.log(entry);
+```
+
+**Extended glob patterns:**
+
+Match test files ending with `.spec.js` or `.test.js`. Note that the `+(spec|test)`
+pattern also matches files like `foo.spectest.js`.
+
+```mjs
+import { glob } from 'node:fs/promises';
 
-// Extended glob patterns
 for await (const entry of glob('test/**/*.+(spec|test).js'))
-  console.log(entry); // Test files ending with .spec.js or .test.js
-  // Note: This also matches files like 'foo.spectest.js'
+  console.log(entry);
+```
+
+For more precise matching, use brace expansion instead:
+
+```mjs
+import { glob } from 'node:fs/promises';
 
-// More precise pattern using brace expansion
 for await (const entry of glob('test/**/*.{spec,test}.js'))
-  console.log(entry); // Only matches .spec.js or .test.js files
+  console.log(entry);
+```
 
-// Excluding patterns
-for await (const entry of glob('**/*.js', { exclude: ['node_modules/**'] }))
-  console.log(entry); // All .js files except those in node_modules
+**Excluding patterns:**
 
-// Multiple patterns
-for await (const entry of glob(['src/**/*.js', 'lib/**/*.js']))
-  console.log(entry); // .js files in both src and lib directories
+Match all `.js` files except those in `node_modules`.
+
+```mjs
+import { glob } from 'node:fs/promises';
+
+for await (const entry of glob('**/*.js', { exclude: ['node_modules/**'] }))
+  console.log(entry);
 ```
 
-```cjs
-const { glob } = require('node:fs/promises');
+**Multiple patterns:**
 
-(async () => {
-  for await (const entry of glob('**/*.js'))
-    console.log(entry);
-})();
+Match `.js` files in both `src` and `lib` directories.
+
+```mjs
+import { glob } from 'node:fs/promises';
+
+for await (const entry of glob(['src/**/*.js', 'lib/**/*.js']))
+  console.log(entry);
 ```
 
 #### Platform Considerations
 
 * **Case sensitivity**: Glob patterns are case-insensitive on Windows and macOS,
-  case-sensitive on other platforms
+  case-sensitive on other platforms.
 * **Path separators**: Forward slashes (`/`) are used in patterns regardless of
-  platform; they are automatically converted to the appropriate separator
+  platform; they are automatically converted to the appropriate separator.
 * **Returned paths**: Results use platform-specific path separators (`\` on Windows,
   `/` on POSIX). Paths are relative to `options.cwd` if provided, otherwise
-  relative to the current working directory
-* **Symlinks**: Symbolic links are followed and their targets are included in results
+  relative to the current working directory.
+* **Symlinks**: Symbolic links are followed and their targets are included in results.
 * **Hidden files**: Files starting with `.` are included in results when explicitly
-  matched, but not when using `*` or `**` patterns
+  matched, but not when using `*` or `**` patterns.
 
 #### Performance Notes
 
 * Results are streamed as an async iterator, allowing for efficient memory usage
-  with large result sets
-* The implementation includes internal caching to avoid duplicate file system operations
+  with large result sets.
+* The implementation includes internal caching to avoid duplicate file system operations.
 * For better performance with large directory trees, consider using more specific
-  patterns to reduce the search scope
+  patterns to reduce the search scope.
 
 [`path.matchesGlob()`][] supports the same basic glob pattern syntax for
 in-memory path matching, but does not include the `exclude` option.
@@ -3245,7 +3313,7 @@ changes:
     Windows, `/` on POSIX) and are relative to `options.cwd` if provided,
     otherwise relative to the current working directory.
 
-Retrieves the files matching the specified pattern(s).
+Retrieves the file paths matching the specified pattern(s).
 
 See `fsPromises.glob()` for detailed information about pattern syntax,
 examples, and behavior.
@@ -5801,7 +5869,7 @@ changes:
   Windows, `/` on POSIX) and are relative to `options.cwd` if provided,
   otherwise relative to the current working directory.
 
-Retrieves the files matching the specified pattern(s).
+Retrieves the file paths matching the specified pattern(s).
 
 See `fsPromises.glob()` for detailed information about pattern syntax,
 examples, and behavior.