Add JSDoc types (#5842)

* Enhance TypeScript definitions for Plausible tracking library

Updated the plausible.d.ts file to improve documentation by adding JSDoc comments for all functions and properties. This enhances clarity and usability for developers integrating the tracking library.

* Update CHANGELOG.md to reflect changes in TypeScript definition comments for improved IDE integration

* Format

* Remove subtitle from changelog

---------

Co-authored-by: Ahmed Hassanein <[email protected]>

Author: apata

tracker/npm_package/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Convert all TypeScript definition comments from `//` style to JSDoc `/** */` style for better IDE integration and TypeScript tooling support
+
 ## [0.4.3] - 2025-09-15
 
 - Fix formatting issues.

tracker/npm_package/plausible.d.ts

@@ -1,110 +1,130 @@
-// Sets up the tracking library. Can be called once.
+/** Sets up the tracking library. Can be called once. */
 export function init(config: PlausibleConfig): void
 
-// Tracks an event, requires `init` to be called first.
+/** Tracks an event, requires `init` to be called first. */
 export function track(eventName: string, options: PlausibleEventOptions): void
 
 export interface PlausibleConfig {
-  // Your site's domain, as declared by you in Plausible's settings.
+  /** Your site's domain, as declared by you in Plausible's settings. */
   domain: string
 
-  // The URL of the Plausible API endpoint. Defaults to https://plausible.io/api/event
-  // See proxying guide at https://plausible.io/docs/proxy/introduction
+  /**
+   * The URL of the Plausible API endpoint. Defaults to https://plausible.io/api/event
+   * See proxying guide at https://plausible.io/docs/proxy/introduction
+   */
   endpoint?: string
 
-  // Whether to automatically capture pageviews. Defaults to true.
+  /** Whether to automatically capture pageviews. Defaults to true. */
   autoCapturePageviews?: boolean
 
-  // Whether the page uses hash based routing. Defaults to false.
-  // Read more at https://plausible.io/docs/hash-based-routing
+  /**
+   * Whether the page uses hash based routing. Defaults to false.
+   * Read more at https://plausible.io/docs/hash-based-routing
+   */
   hashBasedRouting?: boolean
 
-  // Whether to track outbound link clicks. Defaults to false.
+  /** Whether to track outbound link clicks. Defaults to false. */
   outboundLinks?: boolean
 
-  // Whether to track file downloads. Defaults to false.
+  /** Whether to track file downloads. Defaults to false. */
   fileDownloads?: boolean | { fileExtensions: string[] }
 
-  // Whether to track form submissions. Defaults to false.
+  /** Whether to track form submissions. Defaults to false. */
   formSubmissions?: boolean
 
-  // Whether to capture events on localhost. Defaults to false.
+  /** Whether to capture events on localhost. Defaults to false. */
   captureOnLocalhost?: boolean
 
-  // Whether to log on ignored events. Defaults to true.
+  /** Whether to log on ignored events. Defaults to true. */
   logging?: boolean
 
-  // Custom properties to add to all events tracked.
-  // If passed as a function, it will be called when `track` is called.
+  /**
+   * Custom properties to add to all events tracked.
+   * If passed as a function, it will be called when `track` is called.
+   */
   customProperties?:
     | CustomProperties
     | ((eventName: string) => CustomProperties)
 
-  // A function that can be used to transform the payload before it is sent to the API.
-  // If the function returns null or any other falsy value, the event will be ignored.
-  //
-  // This can be used to avoid sending certain types of events, or modifying any event
-  // parameters, e.g. to clean URLs of values that should not be recorded.
+  /**
+   * A function that can be used to transform the payload before it is sent to the API.
+   * If the function returns null or any other falsy value, the event will be ignored.
+   *
+   * This can be used to avoid sending certain types of events, or modifying any event
+   * parameters, e.g. to clean URLs of values that should not be recorded.
+   */
   transformRequest?: (
     payload: PlausibleRequestPayload
   ) => PlausibleRequestPayload | null
 
-  // If enabled (the default), the script will set `window.plausible` after `init` is called.
-  // This is used by the verifier to detect if the script is loaded from npm package.
+  /**
+   * If enabled (the default), the script will set `window.plausible` after `init` is called.
+   * This is used by the verifier to detect if the script is loaded from npm package.
+   */
   bindToWindow?: boolean
 }
 
 export interface PlausibleEventOptions {
-  // Custom properties to add to the event.
-  // Read more at https://plausible.io/docs/custom-props/introduction
+  /**
+   * Custom properties to add to the event.
+   * Read more at https://plausible.io/docs/custom-props/introduction
+   */
   props?: CustomProperties
 
-  // Whether the tracked event is interactive. Defaults to true.
-  // By marking a custom event as non-interactive, it will not be counted towards bounce rate calculations.
+  /**
+   * Whether the tracked event is interactive. Defaults to true.
+   * By marking a custom event as non-interactive, it will not be counted towards bounce rate calculations.
+   */
   interactive?: boolean
 
-  // Revenue data to add to the event.
-  // Read more at https://plausible.io/docs/ecommerce-revenue-tracking
+  /**
+   * Revenue data to add to the event.
+   * Read more at https://plausible.io/docs/ecommerce-revenue-tracking
+   */
   revenue?: PlausibleEventRevenue
 
-  // Called when request to `endpoint` completes or is ignored.
-  // When request is ignored, the result will be undefined.
-  // When request was delivered, the result will be an object with the response status code of the request.
-  // When there was a network error, the result will be an object with the error object.
+  /**
+   * Called when request to `endpoint` completes or is ignored.
+   * When request is ignored, the result will be undefined.
+   * When request was delivered, the result will be an object with the response status code of the request.
+   * When there was a network error, the result will be an object with the error object.
+   */
   callback?: (
     result?: { status: number } | { error: unknown } | undefined
   ) => void
 
-  // Overrides the URL of the page that the event is being tracked on.
-  // If not provided, `location.href` will be used.
+  /**
+   * Overrides the URL of the page that the event is being tracked on.
+   * If not provided, `location.href` will be used.
+   */
   url?: string
 }
 
 export type CustomProperties = Record<string, string>
 
 export type PlausibleEventRevenue = {
-  // Revenue amount in `currency`
+  /** Revenue amount in `currency` */
   amount: number | string
-  // Currency is an ISO 4217 string representing the currency code, e.g. "USD" or "EUR"
+  /** Currency is an ISO 4217 string representing the currency code, e.g. "USD" or "EUR" */
   currency: string
 }
 
 export type PlausibleRequestPayload = {
-  // Event name
+  /** Event name */
   n: string
-  // URL of the event
+  /** URL of the event */
   u: string
-  // Domain of the event
+  /** Domain of the event */
   d: string
-  // Referrer
+  /** Referrer */
   r?: string | null
-  // Custom properties
+  /** Custom properties */
   p?: CustomProperties
-  // Revenue information
+  /** Revenue information */
   $?: PlausibleEventRevenue
-  // Whether the event is interactive
+  /** Whether the event is interactive */
   i?: boolean
 } & Record<string, unknown>
 
-// Default file types that are tracked when `fileDownloads` is enabled.
+/** Default file types that are tracked when `fileDownloads` is enabled. */
 export const DEFAULT_FILE_TYPES: string[]