Improve api docs

gliviu · Aug 13, 2023 · bb5b266 · bb5b266
1 parent f7eb039
commit bb5b266
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 81 deletions.
diff --git a/package.json b/package.json
@@ -29,7 +29,7 @@
         "extest": "npm run pretest && ./test/extended/init.sh && test/extended/runall.sh",
         "coverage": "npx nyc --exclude \"build/test/**\" --reporter=lcov npm test && npx nyc report",
         "toc": "npx markdown-toc README.md; echo \n",
-        "docs": "typedoc --includeVersion --excludeExternals --excludeInternal --readme none --gitRevision master --out docs ./src/index.ts"
+        "docs": "typedoc --includeVersion --excludeExternals --excludeInternal --readme none --gitRevision master -cleanOutputDir --sort source-order --out docs ./src/index.ts"
     },
     "dependencies": {
         "minimatch": "^3.0.4",

diff --git a/src/index.ts b/src/index.ts
@@ -101,28 +101,28 @@ export function compare(path1: string, path2: string, options?: Options): Promis
 }
 
 /**
- * File content comparison handlers.
- * These comparators are included with dir-compare.
+ * List of {@link CompareFileHandler}s included with dir-compare.
  * 
- * The `defaultFileCompare` is used when {@link Options.compareContent} is enabled 
- * and {@link Options.compareFileSync} or {@link Options.compareFileAsync} are sent as `undefined`.
- * 
- * See [Custom file content comparators](https://github.com/gliviu/dir-compare#custom-file-content-comparators) for details.
+ * See [File content comparators](https://github.com/gliviu/dir-compare#file-content-comparators) for details.
  */
 export const fileCompareHandlers: FileCompareHandlers = {
     defaultFileCompare,
     lineBasedFileCompare
 }
 
 /**
- * Name comparison included with dir-compare.
+ * List of {@link CompareNameHandler}s included with dir-compare.
+ * 
+ * See [Name comparators](https://github.com/gliviu/dir-compare#name-comparators) for details.
  */
 export const compareNameHandlers: CompareNameHandlers = {
     defaultNameCompare
 }
 
 /**
- * Filter handlers included with dir-compare.
+ * List of {@link FilterHandler}s included with dir-compare.
+ * 
+ * See [Glob filter](https://github.com/gliviu/dir-compare#glob-filter) for details.
  */
 export const filterHandlers: FilterHandlers = {
     defaultFilterHandler

diff --git a/src/types.ts b/src/types.ts
@@ -83,7 +83,7 @@ export interface Options {
     includeFilter?: string
 
     /**
-     * File/directory name exclude filter. Comma separated minimatch patterns. See [Glob patterns](https://github.com/gliviu/dir-compare#glob-patterns)
+     * File/directory name exclude filter. Comma separated minimatch patterns. See [Glob patterns](https://github.com/gliviu/dir-compare#glob-patterns).
      */
     excludeFilter?: string
 
@@ -128,31 +128,37 @@ export interface Options {
     handlePermissionDenied?: boolean
 
     /**
-     * Callback for constructing result. Called for each compared entry pair.
+     * Extension point used for constructing the {@link Result} object.
      * 
-     * Updates 'statistics' and 'diffSet'.
-     * 
-     * See [Custom result builder](https://github.com/gliviu/dir-compare#custom-result-builder).
+     * See [Result builder](https://github.com/gliviu/dir-compare#result-builder).
      */
     resultBuilder?: ResultBuilder
 
     /**
-     * File content comparison handler. See [Custom file comparators](https://github.com/gliviu/dir-compare#custom-file-content-comparators).
+     * Extension point used to perform sync file content comparison.
+     * 
+     * See [File comparators](https://github.com/gliviu/dir-compare#file-content-comparators).
      */
     compareFileSync?: CompareFileSync
 
     /**
-     * File content comparison handler. See [Custom file comparators](https://github.com/gliviu/dir-compare#custom-file-content-comparators).
+     * Extension point used to perform async file content comparison.
+     * 
+     * See [File comparators](https://github.com/gliviu/dir-compare#file-content-comparators).
      */
     compareFileAsync?: CompareFileAsync
 
     /**
-     * Entry name comparison handler. See [Custom name comparators](https://github.com/gliviu/dir-compare#custom-name-comparators).
+     * Extension point used to compare files or directories names.
+     * 
+     * See [Name comparators](https://github.com/gliviu/dir-compare#name-comparators).
      */
     compareNameHandler?: CompareNameHandler
 
     /**
-     * Filter handler. todo: See [Custom name comparators](https://github.com/gliviu/dir-compare#custom-name-comparators).
+     * Extension point used to control which files or directories should be included in the comparison.
+     * 
+     * See [Glob filter](https://github.com/gliviu/dir-compare#glob-filter).
      */
     filterHandler?: FilterHandler
 }
@@ -167,36 +173,6 @@ export type DiffSet = Array<Difference>
  */
 export type OptionalDiffSet = DiffSet | undefined
 
-/**
- * Callback for constructing comparison result. Called for each compared entry pair.
- * 
- * Updates 'statistics' and 'diffSet'.
- */
-export type ResultBuilder =
-    /**
-     * @param entry1 Left entry.
-     * @param entry2 Right entry.
-     * @param state See [[DifferenceState]].
-     * @param level Depth level relative to root dir.
-     * @param relativePath Path relative to root dir.
-     * @param statistics Statistics to be updated.
-     * @param diffSet Status per each entry to be appended.
-     * Do not append if [[Options.noDiffSet]] is false.
-     * @param reason See [[Reason]]. Not available if entries are equal.
-     */
-    (
-        entry1: Entry | undefined,
-        entry2: Entry | undefined,
-        state: DifferenceState,
-        level: number,
-        relativePath: string,
-        options: Options,
-        statistics: InitialStatistics,
-        diffSet: DiffSet | undefined,
-        reason: Reason | undefined,
-        permissionDeniedState: PermissionDeniedState
-    ) => void
-
 export type EntryOrigin = 'left' | 'right'
 
 export interface Entry {
@@ -495,7 +471,7 @@ export interface Difference {
     path2?: string
 
     /**
-     * Path relative to root dir.
+     * Path relative to the root directory of the comparison.
      */
     relativePath: string
 
@@ -569,57 +545,65 @@ export interface Difference {
 }
 
 /**
- * Synchronous file content comparison handler.
+ * Extension point used for constructing the {@link Result} object.
+ * Called for each compared entry pair.
+ * Updates 'statistics' and 'diffSet'.
+ * @param entry1 Left entry.
+ * @param entry2 Right entry.
+ * @param state See [[DifferenceState]].
+ * @param level Depth level relative to root dir.
+ * @param relativePath Path relative to the root directory of the comparison.
+ * @param statistics Statistics to be updated.
+ * @param diffSet Status per each entry to be appended.
+ * Do not append if [[Options.noDiffSet]] is false.
+ * @param reason See [[Reason]]. Not available if entries are equal.
+ */
+export type ResultBuilder = (entry1: Entry | undefined, entry2: Entry | undefined, state: DifferenceState, level: number,
+    relativePath: string, options: Options, statistics: InitialStatistics, diffSet: DiffSet | undefined,
+    reason: Reason | undefined, permissionDeniedState: PermissionDeniedState
+) => void
+
+/**
+ * Extension point used to perform sync file content comparison.
  */
-export type CompareFileSync = (
-    path1: string,
-    stat1: fs.Stats,
-    path2: string,
-    stat2: fs.Stats,
-    options: Options
-) => boolean
+export type CompareFileSync = (path1: string, stat1: fs.Stats,
+    path2: string, stat2: fs.Stats, options: Options) => boolean
 
 /**
- * Asynchronous file content comparison handler.
+ * Extension point used to perform async file content comparison.
  */
-export type CompareFileAsync = (
-    path1: string,
-    stat1: fs.Stats,
-    path2: string,
-    stat2: fs.Stats,
-    options: Options
-) => Promise<boolean>
+export type CompareFileAsync = (path1: string, stat1: fs.Stats,
+    path2: string, stat2: fs.Stats, options: Options) => Promise<boolean>
 
 export interface CompareFileHandler {
     compareSync: CompareFileSync,
     compareAsync: CompareFileAsync
 }
 
 /**
- * Compares the names of two entries.
+ * Extension point used to compare files or directories names.
  * The comparison should be dependent on received options (ie. case sensitive, ...).
  * Returns 0 if names are identical, -1 if name1<name2, 1 if name1>name2.
  */
-export type CompareNameHandler = (
-    name1: string,
-    name2: string,
-    options: Options
-) => 0 | 1 | -1
+export type CompareNameHandler = (name1: string, name2: string, options: Options) => 0 | 1 | -1
 
 /**
- * This is an extension point that provides the capability to determine which files should be included in the comparison.
- * Returns true if the entry is to be processed or false to ignore it.
+ * Extension point used to control which files or directories should be included in the comparison.
+ * 
+ * @param entry Filesystem entry to include or ignore.
+ * @param relativePath Path relative to the root directory of the comparison. It depends on {@link Entry.origin}.
+ * @param option Comparison options.
+ * @returns Returns true if the entry is to be processed or false to ignore it.
  */
-export type FilterHandler = (
-    entry: Entry,
-    relativePath: string,
-    options: Options
-) => boolean
+export type FilterHandler = (entry: Entry, relativePath: string, options: Options) => boolean
 
 export interface FileCompareHandlers {
     /**
-     * This comparison method evaluates files based on their binary content.
-     * It is used if {@link Options.compareFileAsync} or {@link Options.compareFileSync} are not specified.
+     * Compares files based on their binary content.
+     * 
+     * This is the default file content comparator.
+     * It is used when {@link Options.compareContent} is true and custom file comparator
+     * is not specified (ie. {@link Options.compareFileSync} or {@link Options.compareFileAsync} are 'undefined').
      */
     defaultFileCompare: CompareFileHandler;
     /**
@@ -644,7 +628,7 @@ export interface CompareNameHandlers {
 
 export interface FilterHandlers {
     /**
-     * Uses minimatch to accept/ignore files based on {@link Options.includeFilter} and {@link Options.excludeFilter}.
+     * Uses minimatch to include/ignore files based on {@link Options.includeFilter} and {@link Options.excludeFilter}.
      * It is used if {@link Options.filterHandler} is not specified.
      */
     defaultFilterHandler: FilterHandler