3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-06-14 00:32:47 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(utils): JSDoc for all APIs (#6980)

Browse source 
* feat(utils): JSDoc for all APIs

* fix tests
This commit is contained in:
Joshua Chen 2022-03-24 21:34:31 +08:00 • committed by GitHub
parent b8d2a4e84d
commit 2eeb0e46a2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
31 changed files with 637 additions and 255 deletions
Download patch file Download diff file Expand all files Collapse all files

50
packages/docusaurus-utils/src/gitUtils.ts
View file

@ -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';