diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63720a43e..e358cd476 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -99,6 +99,42 @@ the macOS native vibrancy material, which Chromium cannot render. - See [ARCHITECTURE.md](./ARCHITECTURE.md) for the renderer's module layering, state ownership, and side-effect conventions. - Keep commit messages clear and descriptive. +#### 📝 TSDoc + +Every TSDoc block follows the [TSDoc][tsdoc-website] standard. Add TSDoc to +exported APIs whose contract is not obvious from the signature; trivial +presentational components may omit it. Existing files are not the standard: +proposals and new changes follow this section. + +- Start with a one-sentence summary. +- Document every parameter with `@param name - description`. Put optional or + default behaviour in the description; never add JSDoc type annotations. +- Use `@returns` (not `@return`) for every non-void return. Describe the + resolved value, its format, or its success and failure branches. Do not + repeat the TypeScript type or write "Promise resolving to". +- Let named result types own object shapes. Document fields on the type, then + name or link the type from `@returns` instead of restating the shape. +- Use `@throws` for each thrown error condition, `@remarks` for extended + context, `@example` for non-obvious usage, and `@typeParam` for generic + parameters. +- Use `{@link Symbol}` for internal references and backticks for identifiers + and literals. +- Omit `@returns` for `void` and `Promise`. +- Update TSDoc in the same pull request as the behaviour change. Do not + suppress a TSDoc lint finding; fix it or change this convention in a separate + proposal. + +```ts +/** + * Read the token the locally installed GitHub CLI holds for a host. + * + * @param hostname - Host to read the token for (e.g. `github.com`). + * @returns The CLI token, or a classified failure with an optional detail line. + */ +``` + +TSDoc syntax is validated by the shared lint configuration through `pnpm check`. + ### 🐛 How to Report Bugs or Request Features If you encounter a bug or have a feature request, please [open an issue][github-issues] with clear steps to reproduce or a detailed description of your idea. Check for existing issues before creating a new one. @@ -163,6 +199,7 @@ Currently supported forges: **GitHub** (Cloud, Enterprise Server, Enterprise Clo [vite-plus-website]: https://viteplus.dev/ +[tsdoc-website]: https://tsdoc.org/ [conventional-commits]: https://www.conventionalcommits.org [release-please]: https://github.com/googleapis/release-please [github-dependency-dashboard]: https://github.com/gitify-app/gitify/issues/576 diff --git a/src/main/events.ts b/src/main/events.ts index 022ccb466..ef08ca96b 100644 --- a/src/main/events.ts +++ b/src/main/events.ts @@ -42,7 +42,8 @@ export function handleMainEvent( * * @param mb - The menubar instance whose window receives the event. * @param event - The IPC channel/event name to emit. - * @param data - Optional payload sent with the event. + * @param args - Payload arguments for the event; omitted for events with no + * request payload. */ export function sendRendererEvent( mb: Menubar, diff --git a/src/main/handlers/github-cli.ts b/src/main/handlers/github-cli.ts index 7498d6b80..aa3e205cc 100644 --- a/src/main/handlers/github-cli.ts +++ b/src/main/handlers/github-cli.ts @@ -36,7 +36,7 @@ const HOSTNAME_PATTERN = /^[a-z0-9][a-z0-9.-]*$/i; * is the only credential `gh` has. * * @param hostname - Host to read the token for (e.g. `github.com`). - * @returns The token, or the reason the CLI could not supply one. + * @returns The CLI token, or a classified failure with an optional detail line. */ export async function readGitHubCliToken(hostname: string): Promise { if (typeof hostname !== 'string' || !HOSTNAME_PATTERN.test(hostname)) { diff --git a/src/preload/index.ts b/src/preload/index.ts index f760cd767..1dfbc4e0e 100644 --- a/src/preload/index.ts +++ b/src/preload/index.ts @@ -38,7 +38,8 @@ export const api = { * Decrypt an encrypted string using Electron's safe storage. * * @param value - The encrypted string to decrypt. - * @returns A promise resolving to the plaintext string. + * @returns The decrypted token and, when the OS keychain rotated keys, the + * re-encrypted ciphertext to persist. */ decryptValue: (value: string) => invokeMainEvent(EVENTS.SAFE_STORAGE_DECRYPT, value), @@ -46,7 +47,7 @@ export const api = { * Read the token the locally installed GitHub CLI holds for a host. * * @param hostname - Host to read the token for (e.g. `github.com`). - * @returns The token, or the reason the CLI could not supply one. + * @returns The CLI token, or a classified failure with an optional detail line. */ githubCliToken: (hostname: string) => invokeMainEvent(EVENTS.GITHUB_CLI_TOKEN, hostname), @@ -93,6 +94,8 @@ export const api = { /** * Enable or disable the macOS window vibrancy material for Glass. Resolves once * the material has been applied so the renderer can order the visual switch. + * + * @param enabled - `true` to enable the vibrancy material, `false` to remove it. */ setWindowVibrancy: (enabled: boolean) => invokeMainEvent(EVENTS.SET_WINDOW_VIBRANCY, enabled), @@ -100,6 +103,8 @@ export const api = { * Sync the native window appearance (`nativeTheme.themeSource`) with the app's * color mode, so the macOS vibrancy material renders light/dark to match — * otherwise dark Glass gets a light material and its light text washes out. + * + * @param source - The native appearance to apply. */ setNativeTheme: (source: NativeThemeSource) => invokeMainEvent(EVENTS.SET_NATIVE_THEME, source), @@ -136,6 +141,7 @@ export const api = { /** * Set the idle tray icon appearance independently of the app theme. * + * @param value - The idle icon appearance to use. */ setAppearance: (value: TrayIconAppearance) => sendMainEvent(EVENTS.SET_TRAY_ICON_APPEARANCE, value), diff --git a/src/renderer/utils/system/comms.ts b/src/renderer/utils/system/comms.ts index 1cf807994..bfa2fdc12 100644 --- a/src/renderer/utils/system/comms.ts +++ b/src/renderer/utils/system/comms.ts @@ -27,7 +27,7 @@ export function openExternalLink(url: Link): void { /** * Returns the current application version string. * - * @returns Promise resolving to the app version (e.g. `"6.18.0"`). + * @returns The version prefixed with `v`, or `dev` in development. */ export async function getAppVersion(): Promise { return await window.gitify.app.version(); @@ -46,11 +46,9 @@ export async function encryptValue(value: string): Promise { /** * Decrypts a previously encrypted string using the native Electron decryption bridge. * - * Resolves to the decrypted token. When the OS keychain rotated keys during - * decryption, `reEncryptedToken` is also set so callers can persist the new - * ciphertext alongside or in place of the original. - * * @param value - The encrypted string to decrypt. + * @returns The decrypted token and, when the OS keychain rotated keys, the + * re-encrypted ciphertext to persist. */ export async function decryptValue(value: string): Promise { return await window.gitify.decryptValue(value); @@ -59,8 +57,8 @@ export async function decryptValue(value: string): Promise { return await window.gitify.githubCliToken(hostname);