Skip to content

Commit 652580d

Browse files
poteatpoteat
committed
mods: hook JSDoc is a two-line summary and one short paragraph, naming no file path
1 parent 4d63891 commit 652580d

34 files changed

Lines changed: 131 additions & 131 deletions

File tree

‎mods/diff/hooks/backend/backend-of.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,11 @@ import Git from '../git'
22
import type { Backend, BackendHost, BackendProbe } from './types'
33

44
/**
5-
* The backend holding the session's directory: the first of `probes` that
6-
* answers one, else git when a git working tree holds it, else none. The
7-
* probes go first so a probe may claim a working copy by its own rule
8-
* (the nearer of two markers, say); a probe answers null wherever git
5+
* The backend holding the session's directory: another system's when its
6+
* probe answers first, else git when a git working tree holds it, else none.
7+
*
8+
* Other systems are asked first so one may claim a working copy by its own
9+
* rule (the nearer of two markers, say); each answers null wherever git
910
* should govern.
1011
*
1112
* @param host the bound host's runner and probes

‎mods/diff/hooks/backend/installed-backend-probes.ts‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,12 @@
11
import type { BackendProbe } from './types'
22

33
/**
4-
* Where a host adds backends to the plugin: probes for version-control systems
5-
* other than git, consulted in insertion order before git (backendOf); a
6-
* probe answers null wherever git should govern. Empty as shipped, so the
7-
* plugin reads git alone. A host
8-
* that compiles the module in may add a probe once, before the plugin
9-
* registers; the module runs natively, so that probe is what
10-
* `session.start` sees. The module contract offers no other channel: the
11-
* options `register` receives are the manifest's userConfig, and the
12-
* shipped scan requires `register` itself to be a plain exported function.
4+
* Where a host adds backends: probes for version-control systems other than
5+
* git, asked in insertion order before git (backendOf). Empty as shipped.
6+
*
7+
* A host compiling the module in adds a probe once, before the plugin
8+
* registers: the module runs natively, and there is no other channel (the
9+
* options are the manifest's userConfig; the scan wants a plain function).
1310
*/
1411
// module-state-allow: module-evaluation code wiring — a compiling host adds its probe functions (code references, not runtime input) once before registration and never removes or rebinds them; tests pass probes to backendOf directly; a per-Host copy would hold the same functions
1512
export const INSTALLED_BACKEND_PROBES = new Set<BackendProbe>()

‎mods/diff/hooks/backend/types/backend-host/backend-host.ts‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@ import type Git from '../../../git'
22
import type Host from '../../../host'
33

44
/**
5-
* What pinning a backend takes from the bound host: the raw process
6-
* runner (each backend names its own program, argv lead, environment and
7-
* timeout), the file probes, the engine's clock, the session's start as it
8-
* stands at each fetch (a later `session.start` moves it), and the
9-
* branch-base listener.
5+
* What pinning a backend takes from the bound host: its raw process runner,
6+
* file probes, clock, session start and branch-base listener.
7+
*
8+
* Each backend names its own program, argv lead, environment and timeout
9+
* to the runner; the session's start is read as it stands at each fetch
10+
* (a later `session.start` moves it).
1011
*/
1112
export type BackendHost = Pick<Host.Host, 'run' | 'readFile'> &
1213
Pick<Git.GitDeps, 'mtimeOf' | 'entryKindsOf' | 'onBranchBase'> & {

‎mods/diff/hooks/backend/types/backend-probe/backend-probe.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ import type { BackendHost } from '../backend-host'
33

44
/**
55
* Probes the session's directory for one backend's working tree: the
6-
* backend when it holds the directory, null when it does not or when git
7-
* should govern it instead (Git.gitBackendOf is git's).
6+
* backend when it holds the directory, else null.
7+
*
8+
* Null too where git should govern it instead (Git.gitBackendOf is git's).
89
*/
910
export type BackendProbe = (host: BackendHost) => Promise<Backend | null>

‎mods/diff/hooks/backend/types/backend-words/backend-words.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
/**
2-
* The words the pane draws that name the backend: what uncommitted mode
3-
* compares against, the command whose failure the empty state names, the
4-
* tool that lists untracked files, and the note under an untracked row.
2+
* The words the pane draws that name the backend.
3+
*
4+
* What uncommitted mode compares against, the command whose failure the
5+
* empty state names, the tool that lists untracked files, and the note
6+
* under an untracked row.
57
*/
68
export type BackendWords = {
79
/**

‎mods/diff/hooks/backend/types/backend/backend.ts‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,8 @@ import type Git from '../../../git'
22
import type { BackendWords } from '../backend-words'
33

44
/**
5-
* The version-control system behind the pane, pinned once per session:
6-
* where its working tree is, which comparisons it offers, how it words
7-
* them, and the three reads the pane makes of it.
5+
* The version-control system behind the pane, pinned once per session: its
6+
* working tree, what it compares, how it words them, and the pane's reads.
87
*
98
* Git is the plugin's own backend; a host may install probes for others,
109
* consulted where no git working tree holds the directory (backendOf).
@@ -16,7 +15,7 @@ export type Backend = {
1615
repository: Pick<Git.Repository, 'toplevel'>
1716

1817
/**
19-
* The base modes the picker offers, in picker order.
18+
* What the picker offers to compare against, in its order.
2019
*/
2120
baseModes: readonly Git.BaseMode[]
2221

‎mods/diff/hooks/git/git-backend-of.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,10 @@ import type Types from './types'
1111

1212
/**
1313
* The git backend over the session's directory: the repository read with
14-
* one `rev-parse` in that directory, then every child pinned to it
15-
* (`--git-dir`, `--work-tree`, cwd the top) under the C locale and the
16-
* fetch's timeout (gitDiff.ts execPinnedGit).
14+
* one `rev-parse` in that directory, then every child pinned to it.
15+
*
16+
* Each child runs with `--git-dir`, `--work-tree` and cwd the top, under
17+
* the C locale and the fetch's timeout (the built-in's execPinnedGit).
1718
*
1819
* @param host the bound host's runner and probes
1920
* @returns the backend, or null outside a git working tree

‎mods/diff/hooks/git/git-words/git-words.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
import type Backend from '../../backend'
22

33
/**
4-
* The pane's git words: compared with HEAD, read by `git diff`, untracked
5-
* files listed by git and staged with `git add :/…`, unquoted as
6-
* DiffDetailView words it.
4+
* The pane's git words, unquoted as DiffDetailView words them.
5+
*
6+
* Compared with HEAD, read by `git diff`, untracked files listed by git and
7+
* staged with `git add :/…`.
78
*/
89
export const GIT_WORDS: Backend.BackendWords = Object.freeze({
910
base: 'HEAD',

‎mods/diff/hooks/git/parse/is-whole-listing/is-whole-listing.ts‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,11 @@ import { isUnderUtf8Ceiling } from './is-under-utf8-ceiling'
33
import { MOST_UTF8_BYTES } from './most-utf8-bytes'
44

55
/**
6-
* Whether a listing arrived whole: every record terminated (NUL for git's
7-
* `-z` listings, a newline for line records) and the text short of the
8-
* host's output cap, so no record was cut or lost.
6+
* Whether a listing arrived whole, so no record was cut or lost.
97
*
10-
* A cut inside a multi-byte character costs the decoded text up to
11-
* MOST_UTF8_BYTES, hence the margin under the cap.
8+
* Every record is terminated (NUL for `-z` listings, a newline for line
9+
* records) and the text is short of the host's output cap by MOST_UTF8_BYTES,
10+
* what a cut inside a multi-byte character can cost the decoded text.
1211
*
1312
* @param stdout the listing as `$.process.run` returned it
1413
* @param terminator what ends every record; NUL when absent

‎mods/diff/hooks/git/tiers/with-untracked/merged-with-untracked/merged-with-untracked.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@ import { mergedResultOf } from '../merged-result-of'
33

44
/**
55
* A tier's tracked rows and totals with a listed set of untracked rows
6-
* after them (gitDiff.ts mergeSessionUntrackedFiles), or flagged withheld
7-
* when the lister gave no whole listing.
6+
* after them, or flagged withheld when the lister gave no whole listing.
87
*
9-
* A path a tracked row already holds keeps that row and counts once.
8+
* As the built-in's mergeSessionUntrackedFiles merges them, a path a
9+
* tracked row already holds keeps that row and counts once.
1010
*
1111
* @param result the tier's tracked rows and totals
1212
* @param untracked the untracked rows, or null when their listing was withheld

0 commit comments

Comments
 (0)