docs: define TSDoc convention and align IPC docs (#3528)

* docs(preload): align IPC contract documentation

* docs(preload): describe resolved values semantically

* docs: define the TSDoc convention

Author: setchy

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<void>`.
+- 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
 <!-- LINK LABELS -->
 
 [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

src/main/events.ts

@@ -42,7 +42,8 @@ export function handleMainEvent<E extends EventType>(
  *
  * @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<E extends EventType>(
   mb: Menubar,

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<IGitHubCliTokenResult> {
   if (typeof hostname !== 'string' || !HOSTNAME_PATTERN.test(hostname)) {

src/preload/index.ts

@@ -38,15 +38,16 @@ 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),
 
   /**
    * 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,13 +94,17 @@ 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),
 
   /**
    * 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),

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<string> {
   return await window.gitify.app.version();
@@ -46,11 +46,9 @@ export async function encryptValue(value: string): Promise<string> {
 /**
  * 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<ISafeStorageDecryptResult> {
   return await window.gitify.decryptValue(value);
@@ -59,8 +57,8 @@ export async function decryptValue(value: string): Promise<ISafeStorageDecryptRe
 /**
  * Asks the locally installed GitHub CLI for the token it holds for a host.
  *
- * @param hostname The host to read the token for.
- * @returns The token, or the reason the CLI could not supply one.
+ * @param hostname - The host to read the token for.
+ * @returns The CLI token, or a classified failure with an optional detail line.
  */
 export async function readGitHubCliToken(hostname: string): Promise<IGitHubCliTokenResult> {
   return await window.gitify.githubCliToken(hostname);