@docusaurus/utils 0.0.0-4759 → 0.0.0-4760

package/lib/urlUtils.js

@@ -10,6 +10,18 @@ exports.hasSSHProtocol = exports.buildHttpsUrl = exports.buildSshUrl = exports.r
 const tslib_1 = require("tslib");
 const jsUtils_1 = require("./jsUtils");
 const resolve_pathname_1 = tslib_1.__importDefault(require("resolve-pathname"));
+/**
+ * Much like `path.join`, but much better. Takes an array of URL segments, and
+ * joins them into a reasonable URL.
+ *
+ * - `["file:", "/home", "/user/", "website"]` => `file:///home/user/website`
+ * - `["file://", "home", "/user/", "website"]` => `file://home/user/website` (relative!)
+ * - Remove trailing slash before parameters or hash.
+ * - Replace `?` in query parameters with `&`.
+ * - Dedupe forward slashes in the entire path, avoiding protocol slashes.
+ *
+ * @throws {TypeError} If any of the URL segment is not a string, this throws.
+ */
 function normalizeUrl(rawUrls) {
     const urls = [...rawUrls];
     const resultArray = [];
@@ -63,8 +75,8 @@ function normalizeUrl(rawUrls) {
         resultArray.push(component);
     }
     let str = resultArray.join('/');
-    // Each input component is now separated by a single slash
-    // except the possible first plain protocol part.
+    // Each input component is now separated by a single slash except the possible
+    // first plain protocol part.
     // Remove trailing slash before parameters or hash.
     str = str.replace(/\/(?<search>\?|&|#[^!])/g, '$1');
     // Replace ? in parameters with &.
@@ -77,6 +89,11 @@ function normalizeUrl(rawUrls) {
     return str;
 }
 exports.normalizeUrl = normalizeUrl;
+/**
+ * Takes a file's path, relative to its content folder, and computes its edit
+ * URL. If `editUrl` is `undefined`, this returns `undefined`, as is the case
+ * when the user doesn't want an edit URL in her config.
+ */
 function getEditUrl(fileRelativePath, editUrl) {
     return editUrl
         ? // Don't use posixPath for this: we need to force a forward slash path
@@ -85,8 +102,8 @@ function getEditUrl(fileRelativePath, editUrl) {
 }
 exports.getEditUrl = getEditUrl;
 /**
- * Convert filepath to url path.
- * Example: 'index.md' -> '/', 'foo/bar.js' -> '/foo/bar',
+ * Converts file path to a reasonable URL path, e.g. `'index.md'` -> `'/'`,
+ * `'foo/bar.js'` -> `'/foo/bar'`
  */
 function fileToPath(file) {
     const indexRE = /(?<dirname>^|.*\/)index\.(?:mdx?|jsx?|tsx?)$/i;
@@ -97,6 +114,13 @@ function fileToPath(file) {
     return `/${file.replace(extRE, '').replace(/\\/g, '/')}`;
 }
 exports.fileToPath = fileToPath;
+/**
+ * Similar to `encodeURI`, but uses `encodeURIComponent` and assumes there's no
+ * query.
+ *
+ * `encodeURI("/question?/answer")` => `"/question?/answer#section"`;
+ * `encodePath("/question?/answer#section")` => `"/question%3F/answer%23foo"`
+ */
 function encodePath(userPath) {
     return userPath
         .split('/')
@@ -104,6 +128,10 @@ function encodePath(userPath) {
         .join('/');
 }
 exports.encodePath = encodePath;
+/**
+ * Whether `str` is a valid pathname. It must be absolute, and not contain
+ * special characters.
+ */
 function isValidPathname(str) {
     if (!str.startsWith('/')) {
         return false;
@@ -118,24 +146,32 @@ function isValidPathname(str) {
     }
 }
 exports.isValidPathname = isValidPathname;
-// resolve pathname and fail fast if resolution fails
+/**
+ * Resolve pathnames and fail-fast if resolution fails. Uses standard URL
+ * semantics (provided by `resolve-pathname` which is used internally by React
+ * router)
+ */
 function resolvePathname(to, from) {
     return (0, resolve_pathname_1.default)(to, from);
 }
 exports.resolvePathname = resolvePathname;
+/** Appends a leading slash to `str`, if one doesn't exist. */
 function addLeadingSlash(str) {
     return str.startsWith('/') ? str : `/${str}`;
 }
 exports.addLeadingSlash = addLeadingSlash;
 // TODO deduplicate: also present in @docusaurus/utils-common
+/** Appends a trailing slash to `str`, if one doesn't exist. */
 function addTrailingSlash(str) {
     return str.endsWith('/') ? str : `${str}/`;
 }
 exports.addTrailingSlash = addTrailingSlash;
+/** Removes the trailing slash from `str`. */
 function removeTrailingSlash(str) {
     return (0, jsUtils_1.removeSuffix)(str, '/');
 }
 exports.removeTrailingSlash = removeTrailingSlash;
+/** Constructs an SSH URL that can be used to push to GitHub. */
 function buildSshUrl(githubHost, organizationName, projectName, githubPort) {
     if (githubPort) {
         return `ssh://git@${githubHost}:${githubPort}/${organizationName}/${projectName}.git`;
@@ -143,6 +179,7 @@ function buildSshUrl(githubHost, organizationName, projectName, githubPort) {
     return `git@${githubHost}:${organizationName}/${projectName}.git`;
 }
 exports.buildSshUrl = buildSshUrl;
+/** Constructs an HTTP URL that can be used to push to GitHub. */
 function buildHttpsUrl(gitCredentials, githubHost, organizationName, projectName, githubPort) {
     if (githubPort) {
         return `https://${gitCredentials}@${githubHost}:${githubPort}/${organizationName}/${projectName}.git`;
@@ -150,6 +187,11 @@ function buildHttpsUrl(gitCredentials, githubHost, organizationName, projectName
     return `https://${gitCredentials}@${githubHost}/${organizationName}/${projectName}.git`;
 }
 exports.buildHttpsUrl = buildHttpsUrl;
+/**
+ * Whether the current URL is an SSH protocol. In addition to looking for
+ * `ssh:`, it will also allow protocol-less URLs like
+ * `git@github.com:facebook/docusaurus.git`.
+ */
 function hasSSHProtocol(sourceRepoUrl) {
     try {
         if (new URL(sourceRepoUrl).protocol === 'ssh:') {
@@ -159,7 +201,7 @@ function hasSSHProtocol(sourceRepoUrl) {
     }
     catch {
         // Fails when there isn't a protocol
-        return /^(?:[\w-]+@)?[\w.-]+:[\w./-]+/.test(sourceRepoUrl); // git@github.com:facebook/docusaurus.git
+        return /^(?:[\w-]+@)?[\w.-]+:[\w./-]+/.test(sourceRepoUrl);
     }
 }
 exports.hasSSHProtocol = hasSSHProtocol;

package/lib/urlUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"urlUtils.js","sourceRoot":"","sources":["../src/urlUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"urlUtils.js","sourceRoot":"","sources":["../src/urlUtils.ts"],"names":[],"mappings":"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"}

package/lib/webpackUtils.d.ts

@@ -25,6 +25,11 @@ declare type FileLoaderUtils = {
         otherAssets: () => RuleSetRule;
     };
 };
+/**
+ * Returns unified loader configurations to be used for various file types.
+ *
+ * Inspired by https://github.com/gatsbyjs/gatsby/blob/8e6e021014da310b9cc7d02e58c9b3efe938c665/packages/gatsby/src/utils/webpack-utils.ts#L447
+ */
 export declare function getFileLoaderUtils(): FileLoaderUtils;
 export {};
 //# sourceMappingURL=webpackUtils.d.ts.map

package/lib/webpackUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webpackUtils.d.ts","sourceRoot":"","sources":["../src/webpackUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAQzC,aAAK,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE3D,aAAK,eAAe,GAAG;IACrB,OAAO,EAAE;QACP,IAAI,EAAE,CAAC,OAAO,EAAE;YAAC,MAAM,EAAE,WAAW,CAAA;SAAC,KAAK,WAAW,CAAC;QACtD,GAAG,EAAE,CAAC,OAAO,EAAE;YAAC,MAAM,EAAE,WAAW,CAAA;SAAC,KAAK,WAAW,CAAC;QACrD,6BAA6B,EAAE,MAAM,CAAC;QACtC,4BAA4B,EAAE,MAAM,CAAC;KACtC,CAAC;IACF,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,WAAW,CAAC;QAC1B,KAAK,EAAE,MAAM,WAAW,CAAC;QACzB,KAAK,EAAE,MAAM,WAAW,CAAC;QACzB,GAAG,EAAE,MAAM,WAAW,CAAC;QACvB,WAAW,EAAE,MAAM,WAAW,CAAC;KAChC,CAAC;CACH,CAAC;AAGF,wBAAgB,kBAAkB,IAAI,eAAe,CA+GpD"}
+{"version":3,"file":"webpackUtils.d.ts","sourceRoot":"","sources":["../src/webpackUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAQzC,aAAK,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE3D,aAAK,eAAe,GAAG;IACrB,OAAO,EAAE;QACP,IAAI,EAAE,CAAC,OAAO,EAAE;YAAC,MAAM,EAAE,WAAW,CAAA;SAAC,KAAK,WAAW,CAAC;QACtD,GAAG,EAAE,CAAC,OAAO,EAAE;YAAC,MAAM,EAAE,WAAW,CAAA;SAAC,KAAK,WAAW,CAAC;QACrD,6BAA6B,EAAE,MAAM,CAAC;QACtC,4BAA4B,EAAE,MAAM,CAAC;KACtC,CAAC;IACF,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,WAAW,CAAC;QAC1B,KAAK,EAAE,MAAM,WAAW,CAAC;QACzB,KAAK,EAAE,MAAM,WAAW,CAAC;QACzB,GAAG,EAAE,MAAM,WAAW,CAAC;QACvB,WAAW,EAAE,MAAM,WAAW,CAAC;KAChC,CAAC;CACH,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAmHpD"}

package/lib/webpackUtils.js

@@ -11,13 +11,17 @@ const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const pathUtils_1 = require("./pathUtils");
 const constants_1 = require("./constants");
-// Inspired by https://github.com/gatsbyjs/gatsby/blob/8e6e021014da310b9cc7d02e58c9b3efe938c665/packages/gatsby/src/utils/webpack-utils.ts#L447
+/**
+ * Returns unified loader configurations to be used for various file types.
+ *
+ * Inspired by https://github.com/gatsbyjs/gatsby/blob/8e6e021014da310b9cc7d02e58c9b3efe938c665/packages/gatsby/src/utils/webpack-utils.ts#L447
+ */
 function getFileLoaderUtils() {
     // files/images < urlLoaderLimit will be inlined as base64 strings directly in
     // the html
     const urlLoaderLimit = constants_1.WEBPACK_URL_LOADER_LIMIT;
     // defines the path/pattern of the assets handled by webpack
-    const fileLoaderFileName = (folder) => `${constants_1.OUTPUT_STATIC_ASSETS_DIR_NAME}/${folder}/[name]-[contenthash].[ext]`;
+    const fileLoaderFileName = (folder) => path_1.default.posix.join(constants_1.OUTPUT_STATIC_ASSETS_DIR_NAME, folder, '[name]-[contenthash].[ext]');
     const loaders = {
         file: (options) => ({
             loader: require.resolve(`file-loader`),

package/lib/webpackUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"webpackUtils.js","sourceRoot":"","sources":["../src/webpackUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webpackUtils.js","sourceRoot":"","sources":["../src/webpackUtils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/utils",
-  "version": "0.0.0-4759",
+  "version": "0.0.0-4760",
   "description": "Node utility functions for Docusaurus packages.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,7 +18,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "0.0.0-4759",
+    "@docusaurus/logger": "0.0.0-4760",
     "@svgr/webpack": "^6.2.1",
     "file-loader": "^6.2.0",
     "fs-extra": "^10.0.1",
@@ -38,12 +38,12 @@
     "node": ">=14"
   },
   "devDependencies": {
-    "@docusaurus/types": "0.0.0-4759",
+    "@docusaurus/types": "0.0.0-4760",
     "@types/dedent": "^0.7.0",
     "@types/github-slugger": "^1.3.0",
     "@types/micromatch": "^4.0.2",
     "@types/react-dom": "^17.0.14",
     "dedent": "^0.7.0"
   },
-  "gitHead": "27c0191b8a17b392b946c59f5ae8d56f787ffd0e"
+  "gitHead": "ca58c5f867aec349fb405a2056d4bdb4d140a0b5"
 }

package/src/constants.ts

@@ -5,34 +5,86 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/** Node major version, directly read from env. */
 export const NODE_MAJOR_VERSION = parseInt(
   process.versions.node.split('.')[0]!,
   10,
 );
+/** Node minor version, directly read from env. */
 export const NODE_MINOR_VERSION = parseInt(
   process.versions.node.split('.')[1]!,
   10,
 );
 
-// Can be overridden with cli option --out-dir
+/**
+ * Can be overridden with cli option `--out-dir`. Code should generally use
+ * `context.outDir` instead (which is always absolute and localized).
+ */
 export const DEFAULT_BUILD_DIR_NAME = 'build';
 
-// Can be overridden with cli option --config
+/**
+ * Can be overridden with cli option `--config`. Code should generally use
+ * `context.siteConfigPath` instead (which is always absolute).
+ */
 export const DEFAULT_CONFIG_FILE_NAME = 'docusaurus.config.js';
 
+/** Can be absolute or relative to site directory. */
 export const BABEL_CONFIG_FILE_NAME =
-  process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME || 'babel.config.js';
+  process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME ?? 'babel.config.js';
 
+/**
+ * Can be absolute or relative to site directory. Code should generally use
+ * `context.generatedFilesDir` instead (which is always absolute).
+ */
 export const GENERATED_FILES_DIR_NAME =
-  process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME || '.docusaurus';
+  process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME ?? '.docusaurus';
 
+/**
+ * We would assume all of the site's JS code lives in here and not outside.
+ * Relative to the site directory.
+ */
 export const SRC_DIR_NAME = 'src';
-export const STATIC_DIR_NAME = 'static';
-export const OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets'; // files handled by webpack, hashed (can be cached aggressively)
+
+/**
+ * Can be overridden with `config.staticDirectories`. Code should use
+ * `context.siteConfig.staticDirectories` instead (which is always absolute).
+ */
+export const DEFAULT_STATIC_DIR_NAME = 'static';
+
+/**
+ * Files here are handled by webpack, hashed (can be cached aggressively).
+ * Relative to the build output folder.
+ */
+export const OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets';
+
+/**
+ * Components in this directory will receive the `@theme` alias and be able to
+ * shadow default theme components.
+ */
 export const THEME_PATH = `${SRC_DIR_NAME}/theme`;
+
+/**
+ * All translation-related data live here, relative to site directory. Content
+ * will be namespaced by locale.
+ */
+export const I18N_DIR_NAME = 'i18n';
+
+/**
+ * Translations for React code.
+ */
+export const CODE_TRANSLATIONS_FILE_NAME = 'code.json';
+
+/** Dev server opens on this port by default. */
 export const DEFAULT_PORT = 3000;
+
+/** Default plugin ID. */
 export const DEFAULT_PLUGIN_ID = 'default';
 
-// Temporary fix for https://github.com/facebook/docusaurus/issues/5493
+/**
+ * Allow overriding the limit after which the url loader will no longer inline
+ * assets.
+ *
+ * @see https://github.com/facebook/docusaurus/issues/5493
+ */
 export const WEBPACK_URL_LOADER_LIMIT =
   process.env.WEBPACK_URL_LOADER_LIMIT ?? 10000;

package/src/dataFileUtils.ts

@@ -13,15 +13,25 @@ import type {ContentPaths} from './markdownLinks';
 import logger from '@docusaurus/logger';
 
 type DataFileParams = {
+  /** Path to the potential data file, relative to `contentPaths` */
   filePath: string;
+  /**
+   * Includes the base path and localized path, both of which are eligible for
+   * sourcing data files. Both paths should be absolute.
+   */
   contentPaths: ContentPaths;
 };
 
+/**
+ * Looks for a data file in the potential content paths; loads a localized data
+ * file in priority.
+ *
+ * @returns An absolute path to the data file, or `undefined` if there isn't one.
+ */
 export async function getDataFilePath({
   filePath,
   contentPaths,
 }: DataFileParams): Promise<string | undefined> {
-  // Loads a localized data file in priority
   const contentPath = await findFolderContainingFile(
     getContentPathList(contentPaths),
     filePath,
@@ -33,11 +43,17 @@ export async function getDataFilePath({
 }
 
 /**
- * Looks up for a data file in the content paths, returns the normalized object.
- * Throws when validation fails; returns undefined when file not found
+ * Looks up for a data file in the content paths, returns the object validated
+ * and normalized according to the `validate` callback.
+ *
+ * @returns `undefined` when file not found
+ * @throws Throws when validation fails, displaying a helpful context message.
  */
 export async function getDataFileData<T>(
-  params: DataFileParams & {fileType: string},
+  params: DataFileParams & {
+    /** Used for the "The X file looks invalid" message. */
+    fileType: string;
+  },
   validate: (content: unknown) => T,
 ): Promise<T | undefined> {
   const filePath = await getDataFilePath(params);
@@ -54,12 +70,21 @@ export async function getDataFileData<T>(
   }
 }
 
-// Order matters: we look in priority in localized folder
+/**
+ * Takes the `contentPaths` data structure and returns an ordered path list
+ * indicating their priorities. For all data, we look in the localized folder
+ * in priority.
+ */
 export function getContentPathList(contentPaths: ContentPaths): string[] {
   return [contentPaths.contentPathLocalized, contentPaths.contentPath];
 }
 
-// return the first folder path in which the file exists in
+/**
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists, or `undefined` if
+ * none is found.
+ */
 export async function findFolderContainingFile(
   folderPaths: string[],
   relativeFilePath: string,
@@ -69,6 +94,16 @@ export async function findFolderContainingFile(
   );
 }
 
+/**
+ * Fail-fast alternative to `findFolderContainingFile`.
+ *
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists.
+ * @throws Throws if no file can be found. You should use this method only when
+ * you actually know the file exists (e.g. when the `relativeFilePath` is read
+ * with a glob and you are just trying to localize it)
+ */
 export async function getFolderContainingFile(
   folderPaths: string[],
   relativeFilePath: string,
@@ -77,12 +112,10 @@ export async function getFolderContainingFile(
     folderPaths,
     relativeFilePath,
   );
-  // should never happen, as the source was read from the FS anyway...
   if (!maybeFolderPath) {
     throw new Error(
-      `File "${relativeFilePath}" does not exist in any of these folders:\n- ${folderPaths.join(
-        '\n- ',
-      )}`,
+      `File "${relativeFilePath}" does not exist in any of these folders:
+- ${folderPaths.join('\n- ')}`,
     );
   }
   return maybeFolderPath;

package/src/emitUtils.ts

@@ -13,6 +13,16 @@ import {findAsyncSequential} from './jsUtils';
 
 const fileHash = new Map<string, string>();
 
+/**
+ * Outputs a file to the generated files directory. Only writes files if content
+ * differs from cache (for hot reload performance).
+ *
+ * @param generatedFilesDir Absolute path.
+ * @param file Path relative to `generatedFilesDir`.
+ * @param content String content to write.
+ * @param skipCache If `true` (defaults as `true` for production), file is
+ * force-rewritten, skipping cache.
+ */
 export async function generate(
   generatedFilesDir: string,
   file: string,
@@ -23,14 +33,21 @@ export async function generate(
 
   if (skipCache) {
     await fs.outputFile(filepath, content);
+    // Cache still needs to be reset, otherwise, writing "A", "B", and "A" where
+    // "B" skips cache will cause the last "A" not be able to overwrite as the
+    // first "A" remains in cache. But if the file never existed in cache, no
+    // need to register it.
+    if (fileHash.get(filepath)) {
+      fileHash.set(filepath, createHash('md5').update(content).digest('hex'));
+    }
     return;
   }
 
   let lastHash = fileHash.get(filepath);
 
-  // If file already exists but its not in runtime cache yet,
-  // we try to calculate the content hash and then compare
-  // This is to avoid unnecessary overwriting and we can reuse old file.
+  // If file already exists but it's not in runtime cache yet, we try to
+  // calculate the content hash and then compare. This is to avoid unnecessary
+  // overwriting and we can reuse old file.
   if (!lastHash && (await fs.pathExists(filepath))) {
     const lastContent = await fs.readFile(filepath, 'utf8');
     lastHash = createHash('md5').update(lastContent).digest('hex');
@@ -45,7 +62,7 @@ export async function generate(
   }
 }
 
-const chunkNameCache = new Map();
+const chunkNameCache = new Map<string, string>();
 
 /**
  * Generate unique chunk name given a module path.
@@ -56,7 +73,7 @@ export function genChunkName(
   preferredName?: string,
   shortId: boolean = process.env.NODE_ENV === 'production',
 ): string {
-  let chunkName: string | undefined = chunkNameCache.get(modulePath);
+  let chunkName = chunkNameCache.get(modulePath);
   if (!chunkName) {
     if (shortId) {
       chunkName = simpleHash(modulePath, 8);
@@ -82,6 +99,8 @@ export function genChunkName(
  * @returns This returns a buffer, which you have to decode string yourself if
  * needed. (Not always necessary since the output isn't for human consumption
  * anyways, and most HTML manipulation libs accept buffers)
+ * @throws Throws when the HTML file is not found at any of the potential paths.
+ * This should never happen as it would lead to a 404.
  */
 export async function readOutputHTMLFile(
   permalink: string,

package/src/gitUtils.ts

@@ -8,23 +8,67 @@
 import path from 'path';
 import shell from 'shelljs';
 
+/** Custom error thrown when git is not found in `PATH`. */
 export class GitNotFoundError extends Error {}
 
+/** Custom error thrown when the current file is not tracked by git. */
 export class FileNotTrackedError extends Error {}
 
+/**
+ * Fetches the git history of a file and returns a relevant commit date.
+ * It gets the commit date instead of author date so that amended commits
+ * can have their dates updated.
+ *
+ * @throws {GitNotFoundError} If git is not found in `PATH`.
+ * @throws {FileNotTrackedError} If the current file is not tracked by git.
+ * @throws Also throws when `git log` exited with non-zero, or when it outputs
+ * unexpected text.
+ */
 export function getFileCommitDate(
+  /** Absolute path to the file. */
   file: string,
-  args: {age?: 'oldest' | 'newest'; includeAuthor?: false},
+  args: {
+    /**
+     * `"oldest"` is the commit that added the file, following renames;
+     * `"newest"` is the last commit that edited the file.
+     */
+    age?: 'oldest' | 'newest';
+    /** Use `includeAuthor: true` to get the author information as well. */
+    includeAuthor?: false;
+  },
 ): {
+  /** Relevant commit date. */
   date: Date;
+  /** Timestamp in **seconds**, as returned from git. */
   timestamp: number;
 };
+/**
+ * Fetches the git history of a file and returns a relevant commit date.
+ * It gets the commit date instead of author date so that amended commits
+ * can have their dates updated.
+ *
+ * @throws {GitNotFoundError} If git is not found in `PATH`.
+ * @throws {FileNotTrackedError} If the current file is not tracked by git.
+ * @throws Also throws when `git log` exited with non-zero, or when it outputs
+ * unexpected text.
+ */
 export function getFileCommitDate(
+  /** Absolute path to the file. */
   file: string,
-  args: {age?: 'oldest' | 'newest'; includeAuthor: true},
+  args: {
+    /**
+     * `"oldest"` is the commit that added the file, following renames;
+     * `"newest"` is the last commit that edited the file.
+     */
+    age?: 'oldest' | 'newest';
+    includeAuthor: true;
+  },
 ): {
+  /** Relevant commit date. */
   date: Date;
+  /** Timestamp in **seconds**, as returned from git. */
   timestamp: number;
+  /** The author's name, as returned from git. */
   author: string;
 };
 export function getFileCommitDate(
@@ -53,8 +97,6 @@ export function getFileCommitDate(
     );
   }
 
-  // Commit time and author name; not using author time so that amended commits
-  // can have their dates updated
   let formatArg = '--format=%ct';
   if (includeAuthor) {
     formatArg += ',%an';