docs: #161 Document methods using tsdoc format (#274)

* add eslint tsdoc plugin

* configured tsdoc eslint

* configured tsdoc eslint

* documented public methods raygun.batch.ts

* documented lib/raygun.breadcrumbs.express.ts

* document methods in lib/raygun.breadcrumbs.ts

* documented lib/raygun.human.ts

* documented lib/raygun.messageBuilder.ts

* fix docs in lib/raygun.sync.transport.ts

* fix docs lib/raygun.transport.ts

* fix docs in lib/raygun.ts

Author: miquelbeltran

eslint.config.mjs

@@ -4,6 +4,7 @@ import eslint from '@eslint/js';
 import stylistic from '@stylistic/eslint-plugin';
 import stylisticTs from '@stylistic/eslint-plugin-ts';
 import tseslint from 'typescript-eslint';
+import tsdocPlugin from 'eslint-plugin-tsdoc';
 
 export default tseslint.config(
     // Basic eslint rules
@@ -15,6 +16,9 @@ export default tseslint.config(
     // Eslint rules for TS
     ...tseslint.configs.recommended,
     {
+        plugins: {
+            ['tsdoc']: tsdocPlugin,
+        },
         languageOptions: {
             // Add node globals to ignore undefined
             globals: {
@@ -59,6 +63,8 @@ export default tseslint.config(
             "@stylistic/ts/no-extra-parens": ["off", 0],
             "@stylistic/ts/quote-props": ["off", 0],
             "@stylistic/ts/space-before-function-paren": ["off", 0],
+            // Documentation format check
+            "tsdoc/syntax": "warn"
         }
     }
 );

lib/raygun.batch.ts

@@ -50,8 +50,8 @@ export class RaygunBatchTransport {
 
   /**
    * Enqueues send request to batch processor.
-   * @param options send options without callback
-   * @return Promise with response or error if rejected
+   * @param options - send options without callback
+   * @returns Promise with response or error if rejected
    */
   send(options: SendOptions): Promise<IncomingMessage> {
     const promise = this.onIncomingMessage(options.message);
@@ -63,6 +63,9 @@ export class RaygunBatchTransport {
     return promise;
   }
 
+  /**
+   * Stops batch transport and clears timerId
+   */
   stopProcessing() {
     if (this.timerId) {
       debug("[raygun.batch.ts] Batch transport - stopping");

lib/raygun.breadcrumbs.express.ts

@@ -6,7 +6,7 @@ const debug = require("debug")("raygun");
 
 /**
  * Parses an ExpressJS Request and adds it to the breadcrumbs store
- * @param request
+ * @param request - ExpressJS request object
  */
 export function addRequestBreadcrumb(request: Request) {
   const crumbs = getBreadcrumbs();

lib/raygun.breadcrumbs.ts

@@ -57,6 +57,11 @@ function getCallsite(): SourceFile | null {
   return callsite;
 }
 
+/**
+ * Adds Breadcrumb to current scope
+ * @param breadcrumb - either String message or BreadcrumbMessage object
+ * @param type - defaults to manual, values as defined in Breadcrumb type
+ */
 export function addBreadcrumb(
   breadcrumb: string | BreadcrumbMessage,
   type: Breadcrumb["type"] = "manual",
@@ -98,6 +103,10 @@ export function addBreadcrumb(
   crumbs.push(internalCrumb);
 }
 
+/**
+ * Obtain list of Breadcrumbs in current scope
+ * @returns List of Breadcrumbs or null if no local storage
+ */
 export function getBreadcrumbs(): Breadcrumb[] | null {
   if (!asyncLocalStorage) {
     return null;
@@ -117,6 +126,11 @@ export function getBreadcrumbs(): Breadcrumb[] | null {
   return newStore;
 }
 
+/**
+ * Run synchronous function in Breadcrumb scope
+ * @param f - function to run
+ * @param store - optional Breadcrumb scope store
+ */
 export function runWithBreadcrumbs(f: () => void, store: Breadcrumb[] = []) {
   if (!asyncLocalStorage) {
     f();
@@ -127,6 +141,11 @@ export function runWithBreadcrumbs(f: () => void, store: Breadcrumb[] = []) {
   asyncLocalStorage.run(store, f);
 }
 
+/**
+ * Run asynchronous function returning a Promise in Breadcrumb scope
+ * @param f - asynchronous function to run
+ * @param store - optional Breadcrumb scope store
+ */
 export function runWithBreadcrumbsAsync<T>(
   f: () => Promise<T>,
   store: Breadcrumb[] = [],
@@ -139,6 +158,9 @@ export function runWithBreadcrumbsAsync<T>(
   return asyncLocalStorage.run(store, f);
 }
 
+/**
+ * Clear the stored Breadcrumbs in current scope
+ */
 export function clear() {
   if (!asyncLocalStorage) {
     return;

lib/raygun.human.ts

@@ -9,12 +9,13 @@ const symbolEqual = "=";
  * - Maximum one level deep
  *
  * Example:
- * - Object "{ name: "Test" }" becomes string "name=Test" as all is the top level
- * - Object "{ one: { name: "Test" }}" becomes string "one={name=Test}" as one level deep is explored
- * - Object "{ one: { two: { name: "Test" }}}" becomes string "one={two=...}" as the max level deep is reached
+ * - Object `{ name: "Test" }` becomes string `name=Test` as all is the top level
+ * - Object `{ one: { name: "Test" }}` becomes string `one={name=Test}` as one level deep is explored
+ * - Object `{ one: { two: { name: "Test" }}}` becomes string `one={two=...}` as the max level deep is reached
  *
- * @param obj input object to stringify
- * @param level level of recursion, should start at 0
+ * @param obj - input object to stringify
+ * @param level - level of recursion, should start at 0
+ * @returns a formatted String
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function humanString(obj: any, level: number = 0): string {

lib/raygun.messageBuilder.ts

@@ -37,9 +37,10 @@ const packageDetails = require("../package.json");
 /**
  * Filter properties in obj according to provided filters.
  * Also removes any recursive self-referencing object.
- * @param obj object to apply filter
- * @param filters list of keys to filter
- * @param explored Set that contains already explored nodes, used internally
+ * @param obj - object to apply filter
+ * @param filters - list of keys to filter
+ * @param explored - Set that contains already explored nodes, used internally
+ * @returns object after applying the filters
  */
 function filterKeys(
   obj: object,
@@ -70,6 +71,12 @@ function filterKeys(
   return _obj;
 }
 
+/**
+ * Extract stacktrace from provided Error
+ * @param error - error to process
+ * @param options - builder options
+ * @returns created stack trace
+ */
 function getStackTrace(
   error: Error,
   options: MessageBuilderOptions,
@@ -98,6 +105,12 @@ function getStackTrace(
   return stack;
 }
 
+/**
+ * Created an error payload to send
+ * @param error - error to process
+ * @param options - builder options
+ * @returns created error
+ */
 function buildError(
   error: IndexableError,
   options: MessageBuilderOptions,
@@ -153,6 +166,10 @@ export class RaygunMessageBuilder {
     return this.message as Message;
   }
 
+  /**
+   * Add error details to builder
+   * @param error - error to add
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   setErrorDetails(error: Error | string | any) {
     if (
@@ -181,6 +198,9 @@ export class RaygunMessageBuilder {
     return this;
   }
 
+  /**
+   * Set environment details from OS to builder
+   */
   setEnvironmentDetails() {
     const environment: Environment = {
       osVersion: `${os.type()} ${os.platform()} ${os.release()}`,
@@ -203,23 +223,39 @@ export class RaygunMessageBuilder {
     return this;
   }
 
+  /**
+   * Set machine name to builder
+   * @param machineName - the machine name, if not provided reads from OS
+   */
   setMachineName(machineName?: string) {
     this.message.details.machineName = machineName || os.hostname();
     return this;
   }
 
+  /**
+   * Set custom data to builder
+   * @param customData - optional CustomData object
+   */
   setUserCustomData(customData?: CustomData) {
     this.message.details.userCustomData = customData;
     return this;
   }
 
+  /**
+   * Set tags to builder
+   * @param tags - List of Tags
+   */
   setTags(tags: Tag[]) {
     if (Array.isArray(tags)) {
       this.message.details.tags = tags;
     }
     return this;
   }
 
+  /**
+   * Set Request to builder
+   * @param request - optional request object
+   */
   setRequestDetails(request: RequestParams | undefined) {
     if (request) {
       const host = "hostname" in request ? request.hostname : request.host;
@@ -237,6 +273,10 @@ export class RaygunMessageBuilder {
     return this;
   }
 
+  /**
+   * Set user info to builder
+   * @param user - either a function or a UserMessageData object
+   */
   setUser(user: (() => UserMessageData) | UserMessageData | undefined) {
     if (!user) {
       return this;
@@ -258,6 +298,10 @@ export class RaygunMessageBuilder {
     return this;
   }
 
+  /**
+   * Set application version to builder
+   * @param version - version as String
+   */
   setVersion(version: string) {
     this.message.details.version = version;
     return this;
@@ -286,6 +330,10 @@ export class RaygunMessageBuilder {
     return data;
   }
 
+  /**
+   * Set list of breadcrumbs to builder
+   * @param breadcrumbs - optional list of breadcrumbs
+   */
   setBreadcrumbs(breadcrumbs: Breadcrumb[] | null) {
     debug(
       `[raygun.messageBuilder.ts] Added breadcrumbs: ${breadcrumbs?.length || 0}`,

lib/raygun.sync.transport.ts

@@ -25,7 +25,7 @@ function syncRequest(httpOptions: SendOptions) {
  * Spawns a synchronous send request.
  * Errors are not returned and callback is ignored.
  * Only used to report uncaught exceptions.
- * @param options
+ * @param options - Send options
  */
 export function send(options: SendOptions) {
   try {

lib/raygun.transport.ts

@@ -25,9 +25,9 @@ export function sendBatch(options: SendOptions): Promise<IncomingMessage> {
 /**
  * Transport implementation that sends error to Raygun.
  * Errors are reported back via callback.
- * @param options without callback
- * @param path service endpoint
- * @return Promise with IncomingMessage or rejected with Error
+ * @param options - without callback
+ * @param path - service endpoint
+ * @returns Promise with IncomingMessage or rejected with Error
  */
 export function send(
   options: SendOptions,