Skip to content

Commit bb5b266

Browse files
gliviugliviu
committed
Improve api docs
1 parent f7eb039 commit bb5b266

3 files changed

Lines changed: 65 additions & 81 deletions

File tree

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
"extest": "npm run pretest && ./test/extended/init.sh && test/extended/runall.sh",
3030
"coverage": "npx nyc --exclude \"build/test/**\" --reporter=lcov npm test && npx nyc report",
3131
"toc": "npx markdown-toc README.md; echo \n",
32-
"docs": "typedoc --includeVersion --excludeExternals --excludeInternal --readme none --gitRevision master --out docs ./src/index.ts"
32+
"docs": "typedoc --includeVersion --excludeExternals --excludeInternal --readme none --gitRevision master -cleanOutputDir --sort source-order --out docs ./src/index.ts"
3333
},
3434
"dependencies": {
3535
"minimatch": "^3.0.4",

‎src/index.ts‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -101,28 +101,28 @@ export function compare(path1: string, path2: string, options?: Options): Promis
101101
}
102102

103103
/**
104-
* File content comparison handlers.
105-
* These comparators are included with dir-compare.
104+
* List of {@link CompareFileHandler}s included with dir-compare.
106105
*
107-
* The `defaultFileCompare` is used when {@link Options.compareContent} is enabled
108-
* and {@link Options.compareFileSync} or {@link Options.compareFileAsync} are sent as `undefined`.
109-
*
110-
* See [Custom file content comparators](https://github.com/gliviu/dir-compare#custom-file-content-comparators) for details.
106+
* See [File content comparators](https://github.com/gliviu/dir-compare#file-content-comparators) for details.
111107
*/
112108
export const fileCompareHandlers: FileCompareHandlers = {
113109
defaultFileCompare,
114110
lineBasedFileCompare
115111
}
116112

117113
/**
118-
* Name comparison included with dir-compare.
114+
* List of {@link CompareNameHandler}s included with dir-compare.
115+
*
116+
* See [Name comparators](https://github.com/gliviu/dir-compare#name-comparators) for details.
119117
*/
120118
export const compareNameHandlers: CompareNameHandlers = {
121119
defaultNameCompare
122120
}
123121

124122
/**
125-
* Filter handlers included with dir-compare.
123+
* List of {@link FilterHandler}s included with dir-compare.
124+
*
125+
* See [Glob filter](https://github.com/gliviu/dir-compare#glob-filter) for details.
126126
*/
127127
export const filterHandlers: FilterHandlers = {
128128
defaultFilterHandler

‎src/types.ts‎

Lines changed: 56 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ export interface Options {
8383
includeFilter?: string
8484

8585
/**
86-
* File/directory name exclude filter. Comma separated minimatch patterns. See [Glob patterns](https://github.com/gliviu/dir-compare#glob-patterns)
86+
* File/directory name exclude filter. Comma separated minimatch patterns. See [Glob patterns](https://github.com/gliviu/dir-compare#glob-patterns).
8787
*/
8888
excludeFilter?: string
8989

@@ -128,31 +128,37 @@ export interface Options {
128128
handlePermissionDenied?: boolean
129129

130130
/**
131-
* Callback for constructing result. Called for each compared entry pair.
131+
* Extension point used for constructing the {@link Result} object.
132132
*
133-
* Updates 'statistics' and 'diffSet'.
134-
*
135-
* See [Custom result builder](https://github.com/gliviu/dir-compare#custom-result-builder).
133+
* See [Result builder](https://github.com/gliviu/dir-compare#result-builder).
136134
*/
137135
resultBuilder?: ResultBuilder
138136

139137
/**
140-
* File content comparison handler. See [Custom file comparators](https://github.com/gliviu/dir-compare#custom-file-content-comparators).
138+
* Extension point used to perform sync file content comparison.
139+
*
140+
* See [File comparators](https://github.com/gliviu/dir-compare#file-content-comparators).
141141
*/
142142
compareFileSync?: CompareFileSync
143143

144144
/**
145-
* File content comparison handler. See [Custom file comparators](https://github.com/gliviu/dir-compare#custom-file-content-comparators).
145+
* Extension point used to perform async file content comparison.
146+
*
147+
* See [File comparators](https://github.com/gliviu/dir-compare#file-content-comparators).
146148
*/
147149
compareFileAsync?: CompareFileAsync
148150

149151
/**
150-
* Entry name comparison handler. See [Custom name comparators](https://github.com/gliviu/dir-compare#custom-name-comparators).
152+
* Extension point used to compare files or directories names.
153+
*
154+
* See [Name comparators](https://github.com/gliviu/dir-compare#name-comparators).
151155
*/
152156
compareNameHandler?: CompareNameHandler
153157

154158
/**
155-
* Filter handler. todo: See [Custom name comparators](https://github.com/gliviu/dir-compare#custom-name-comparators).
159+
* Extension point used to control which files or directories should be included in the comparison.
160+
*
161+
* See [Glob filter](https://github.com/gliviu/dir-compare#glob-filter).
156162
*/
157163
filterHandler?: FilterHandler
158164
}
@@ -167,36 +173,6 @@ export type DiffSet = Array<Difference>
167173
*/
168174
export type OptionalDiffSet = DiffSet | undefined
169175

170-
/**
171-
* Callback for constructing comparison result. Called for each compared entry pair.
172-
*
173-
* Updates 'statistics' and 'diffSet'.
174-
*/
175-
export type ResultBuilder =
176-
/**
177-
* @param entry1 Left entry.
178-
* @param entry2 Right entry.
179-
* @param state See [[DifferenceState]].
180-
* @param level Depth level relative to root dir.
181-
* @param relativePath Path relative to root dir.
182-
* @param statistics Statistics to be updated.
183-
* @param diffSet Status per each entry to be appended.
184-
* Do not append if [[Options.noDiffSet]] is false.
185-
* @param reason See [[Reason]]. Not available if entries are equal.
186-
*/
187-
(
188-
entry1: Entry | undefined,
189-
entry2: Entry | undefined,
190-
state: DifferenceState,
191-
level: number,
192-
relativePath: string,
193-
options: Options,
194-
statistics: InitialStatistics,
195-
diffSet: DiffSet | undefined,
196-
reason: Reason | undefined,
197-
permissionDeniedState: PermissionDeniedState
198-
) => void
199-
200176
export type EntryOrigin = 'left' | 'right'
201177

202178
export interface Entry {
@@ -495,7 +471,7 @@ export interface Difference {
495471
path2?: string
496472

497473
/**
498-
* Path relative to root dir.
474+
* Path relative to the root directory of the comparison.
499475
*/
500476
relativePath: string
501477

@@ -569,57 +545,65 @@ export interface Difference {
569545
}
570546

571547
/**
572-
* Synchronous file content comparison handler.
548+
* Extension point used for constructing the {@link Result} object.
549+
* Called for each compared entry pair.
550+
* Updates 'statistics' and 'diffSet'.
551+
* @param entry1 Left entry.
552+
* @param entry2 Right entry.
553+
* @param state See [[DifferenceState]].
554+
* @param level Depth level relative to root dir.
555+
* @param relativePath Path relative to the root directory of the comparison.
556+
* @param statistics Statistics to be updated.
557+
* @param diffSet Status per each entry to be appended.
558+
* Do not append if [[Options.noDiffSet]] is false.
559+
* @param reason See [[Reason]]. Not available if entries are equal.
560+
*/
561+
export type ResultBuilder = (entry1: Entry | undefined, entry2: Entry | undefined, state: DifferenceState, level: number,
562+
relativePath: string, options: Options, statistics: InitialStatistics, diffSet: DiffSet | undefined,
563+
reason: Reason | undefined, permissionDeniedState: PermissionDeniedState
564+
) => void
565+
566+
/**
567+
* Extension point used to perform sync file content comparison.
573568
*/
574-
export type CompareFileSync = (
575-
path1: string,
576-
stat1: fs.Stats,
577-
path2: string,
578-
stat2: fs.Stats,
579-
options: Options
580-
) => boolean
569+
export type CompareFileSync = (path1: string, stat1: fs.Stats,
570+
path2: string, stat2: fs.Stats, options: Options) => boolean
581571

582572
/**
583-
* Asynchronous file content comparison handler.
573+
* Extension point used to perform async file content comparison.
584574
*/
585-
export type CompareFileAsync = (
586-
path1: string,
587-
stat1: fs.Stats,
588-
path2: string,
589-
stat2: fs.Stats,
590-
options: Options
591-
) => Promise<boolean>
575+
export type CompareFileAsync = (path1: string, stat1: fs.Stats,
576+
path2: string, stat2: fs.Stats, options: Options) => Promise<boolean>
592577

593578
export interface CompareFileHandler {
594579
compareSync: CompareFileSync,
595580
compareAsync: CompareFileAsync
596581
}
597582

598583
/**
599-
* Compares the names of two entries.
584+
* Extension point used to compare files or directories names.
600585
* The comparison should be dependent on received options (ie. case sensitive, ...).
601586
* Returns 0 if names are identical, -1 if name1<name2, 1 if name1>name2.
602587
*/
603-
export type CompareNameHandler = (
604-
name1: string,
605-
name2: string,
606-
options: Options
607-
) => 0 | 1 | -1
588+
export type CompareNameHandler = (name1: string, name2: string, options: Options) => 0 | 1 | -1
608589

609590
/**
610-
* This is an extension point that provides the capability to determine which files should be included in the comparison.
611-
* Returns true if the entry is to be processed or false to ignore it.
591+
* Extension point used to control which files or directories should be included in the comparison.
592+
*
593+
* @param entry Filesystem entry to include or ignore.
594+
* @param relativePath Path relative to the root directory of the comparison. It depends on {@link Entry.origin}.
595+
* @param option Comparison options.
596+
* @returns Returns true if the entry is to be processed or false to ignore it.
612597
*/
613-
export type FilterHandler = (
614-
entry: Entry,
615-
relativePath: string,
616-
options: Options
617-
) => boolean
598+
export type FilterHandler = (entry: Entry, relativePath: string, options: Options) => boolean
618599

619600
export interface FileCompareHandlers {
620601
/**
621-
* This comparison method evaluates files based on their binary content.
622-
* It is used if {@link Options.compareFileAsync} or {@link Options.compareFileSync} are not specified.
602+
* Compares files based on their binary content.
603+
*
604+
* This is the default file content comparator.
605+
* It is used when {@link Options.compareContent} is true and custom file comparator
606+
* is not specified (ie. {@link Options.compareFileSync} or {@link Options.compareFileAsync} are 'undefined').
623607
*/
624608
defaultFileCompare: CompareFileHandler;
625609
/**
@@ -644,7 +628,7 @@ export interface CompareNameHandlers {
644628

645629
export interface FilterHandlers {
646630
/**
647-
* Uses minimatch to accept/ignore files based on {@link Options.includeFilter} and {@link Options.excludeFilter}.
631+
* Uses minimatch to include/ignore files based on {@link Options.includeFilter} and {@link Options.excludeFilter}.
648632
* It is used if {@link Options.filterHandler} is not specified.
649633
*/
650634
defaultFilterHandler: FilterHandler

0 commit comments

Comments
 (0)