From d5bdba01be2aeffafcb12d1f5bcb2e8501db718b Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Sun, 25 Oct 2026 17:09:08 -0400 Subject: [PATCH 1/3] docs(preload): align IPC contract documentation --- src/main/events.ts | 3 ++- src/main/handlers/github-cli.ts | 3 ++- src/preload/index.ts | 12 ++++++++++-- src/renderer/utils/system/comms.ts | 8 +++++--- 4 files changed, 19 insertions(+), 7 deletions(-) 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..b791618c0 100644 --- a/src/main/handlers/github-cli.ts +++ b/src/main/handlers/github-cli.ts @@ -36,7 +36,8 @@ 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 `{ token }` on success, or `{ error, detail? }` when the CLI cannot + * supply one. */ 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..0f6ec5be7 100644 --- a/src/preload/index.ts +++ b/src/preload/index.ts @@ -38,7 +38,9 @@ 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 A promise resolving to `{ token, reEncryptedToken? }`. When the OS + * keychain rotated keys during decryption, `reEncryptedToken` carries the new + * ciphertext so callers can persist it. */ decryptValue: (value: string) => invokeMainEvent(EVENTS.SAFE_STORAGE_DECRYPT, value), @@ -46,7 +48,8 @@ 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 A promise resolving to `{ token }` on success, or + * `{ error, detail? }` when the CLI cannot supply one. */ githubCliToken: (hostname: string) => invokeMainEvent(EVENTS.GITHUB_CLI_TOKEN, hostname), @@ -93,6 +96,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 +105,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 +143,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..6e695142a 100644 --- a/src/renderer/utils/system/comms.ts +++ b/src/renderer/utils/system/comms.ts @@ -27,7 +27,8 @@ 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 Promise resolving to `v` for packaged builds, or `dev` in + * development. */ export async function getAppVersion(): Promise { return await window.gitify.app.version(); @@ -59,8 +60,9 @@ export async function decryptValue(value: string): Promise { return await window.gitify.githubCliToken(hostname); From ce40b96f2832ff7e2b5bff3aa747c56519099e1e Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Sun, 25 Oct 2026 18:03:43 -0400 Subject: [PATCH 2/3] docs(preload): describe resolved values semantically --- src/main/handlers/github-cli.ts | 3 +-- src/preload/index.ts | 8 +++----- src/renderer/utils/system/comms.ts | 12 ++++-------- 3 files changed, 8 insertions(+), 15 deletions(-) diff --git a/src/main/handlers/github-cli.ts b/src/main/handlers/github-cli.ts index b791618c0..aa3e205cc 100644 --- a/src/main/handlers/github-cli.ts +++ b/src/main/handlers/github-cli.ts @@ -36,8 +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 `{ token }` on success, or `{ error, detail? }` when the CLI cannot - * 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 0f6ec5be7..1dfbc4e0e 100644 --- a/src/preload/index.ts +++ b/src/preload/index.ts @@ -38,9 +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 `{ token, reEncryptedToken? }`. When the OS - * keychain rotated keys during decryption, `reEncryptedToken` carries the new - * ciphertext so callers can persist it. + * @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), @@ -48,8 +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 A promise resolving to `{ token }` on success, or - * `{ error, detail? }` when the CLI cannot supply one. + * @returns The CLI token, or a classified failure with an optional detail line. */ githubCliToken: (hostname: string) => invokeMainEvent(EVENTS.GITHUB_CLI_TOKEN, hostname), diff --git a/src/renderer/utils/system/comms.ts b/src/renderer/utils/system/comms.ts index 6e695142a..bfa2fdc12 100644 --- a/src/renderer/utils/system/comms.ts +++ b/src/renderer/utils/system/comms.ts @@ -27,8 +27,7 @@ export function openExternalLink(url: Link): void { /** * Returns the current application version string. * - * @returns Promise resolving to `v` for packaged builds, or `dev` in - * development. + * @returns The version prefixed with `v`, or `dev` in development. */ export async function getAppVersion(): Promise { return await window.gitify.app.version(); @@ -47,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); @@ -61,8 +58,7 @@ export async function decryptValue(value: string): Promise { return await window.gitify.githubCliToken(hostname); From 14529282d55473549d7fb7bba8b62a00b161e227 Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Sun, 25 Oct 2026 18:12:33 -0400 Subject: [PATCH 3/3] docs: define the TSDoc convention --- CONTRIBUTING.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) 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