docs: add missing js docs to methods and types

ngworker · Jun 22, 2023 · 2b86f76 · 2b86f76
1 parent 133e1da
commit 2b86f76
Show file tree

Hide file tree

Showing 8 changed files with 73 additions and 4 deletions.
diff --git a/packages/webworker/lumberjack/src/lib/configuration/create-lumberjack-config.ts b/packages/webworker/lumberjack/src/lib/configuration/create-lumberjack-config.ts
@@ -6,6 +6,12 @@ import { defaultProductionLevels } from './default-production-levels';
 import { LumberjackConfig } from './lumberjack.config';
 import { LumberjackOptions } from './lumberjack.options';
 
+/**
+ * Helps combining the defaults Lumberjack configurations with custom developer configurations.
+ * @param isProductionEnvironment - Lumberjack uses different default log levels based on the environment where is running.
+ * @param options - LumberjackOptions that overwrite the default configuration.
+ * @returns - The combination of default configs and custom overwrites.
+ */
 export function createLumberjackConfig<TPayload extends LumberjackLogPayload | void = void>(
  isProductionEnvironment: boolean,
  options: LumberjackOptions = {}

diff --git a/packages/webworker/lumberjack/src/lib/configuration/default-development-levels.ts b/packages/webworker/lumberjack/src/lib/configuration/default-development-levels.ts
@@ -1,4 +1,7 @@
 import { LumberjackConfigLevels } from '../logs/lumberjack-config-levels';
 import { LumberjackLevel } from '../logs/lumberjack-level';
 
+/*
+ * The default Lumberjack log levels allowed on development.
+ */
 export const defaultDevelopmentLevels: LumberjackConfigLevels = [LumberjackLevel.Verbose];
diff --git a/packages/webworker/lumberjack/src/lib/configuration/default-production-levels.ts b/packages/webworker/lumberjack/src/lib/configuration/default-production-levels.ts
@@ -1,6 +1,9 @@
 import { LumberjackConfigLevels } from '../logs/lumberjack-config-levels';
 import { LumberjackLevel } from '../logs/lumberjack-level';
 
+/*
+ * The default Lumberjack log levels allowed on production.
+ */
 export const defaultProductionLevels: LumberjackConfigLevels = [
  LumberjackLevel.Critical,
  LumberjackLevel.Error,

diff --git a/packages/webworker/lumberjack/src/lib/formatting/create-lumberjack-log-formatter.ts b/packages/webworker/lumberjack/src/lib/formatting/create-lumberjack-log-formatter.ts
@@ -11,6 +11,21 @@ interface LumberjackLogFormatterDependencies<TPayload extends LumberjackLogPaylo
  readonly getUnixEpochTicks: () => number;
 }
 
+/**
+ * Factory function that creates a Lumberjack log formatter function.
+ *
+ * @example
+ * const formatter = createLumberjackLogFormatter(deps);
+ *
+ * const log = {
+ * scope: 'Application',
+ * createdAt: getUnixEpochTicks(),
+ * level: 'ERROR',
+ * message: 'An unexpected error occurred',
+ * };
+ *
+ * console.log(formatter.formatLog(log));
+ */
 export function createLumberjackLogFormatter<TPayload extends LumberjackLogPayload | void = void>(
  deps: LumberjackLogFormatterDependencies<TPayload>
 ) {

diff --git a/packages/webworker/lumberjack/src/lib/formatting/lumberjack-format-log.ts b/packages/webworker/lumberjack/src/lib/formatting/lumberjack-format-log.ts
@@ -3,6 +3,24 @@ import { LumberjackLog } from '../logs/lumberjack.log';
 
 import { utcTimestampFor } from './utc-timestamp-for';
 
+/**
+ * Default function used by Lumberjack to format the Lumberjack logs.
+ *
+ * This function formats a LumberjackLog object into a string with specific format:
+ * "<level> <timestamp> [<scope>] <message>". If the scope is not provided, it will be omitted.
+ *
+ * @example
+ * const log = {
+ * scope: 'Application',
+ * createdAt: new Date(),
+ * level: 'ERROR',
+ * message: 'An unexpected error occurred',
+ * };
+ *
+ * console.log(lumberjackFormatLog(log));
+ * // Outputs: "ERROR 2023-06-22T15:23:42Z [Application] An unexpected error occurred"
+ *
+ */
 export function lumberjackFormatLog<TPayload extends LumberjackLogPayload | void = void>({
  scope,
  createdAt: timestamp,

diff --git a/packages/webworker/lumberjack/src/lib/formatting/lumberjack-log-formatter-result.ts b/packages/webworker/lumberjack/src/lib/formatting/lumberjack-log-formatter-result.ts
@@ -1,6 +1,9 @@
 import { LumberjackLogPayload } from '../logs/lumberjack-log-payload';
 import { LumberjackLog } from '../logs/lumberjack.log';
 
+/**
+ * Represents what a LumberjackLogFormatter->formatLog function will return.
+ */
 export interface LumberjackLogFormatterResult<TPayload extends LumberjackLogPayload | void = void> {
  readonly formattedLog: string;
  readonly log: LumberjackLog<TPayload>;

diff --git a/packages/webworker/lumberjack/src/lib/logging/create-lumberjack.ts b/packages/webworker/lumberjack/src/lib/logging/create-lumberjack.ts
@@ -16,10 +16,24 @@ interface LumberjackDependencies<TPayload extends LumberjackLogPayload | void> {
  getUnixEpochTicks: () => number;
 }
 
-export type Lumberjack<TPayload extends LumberjackLogPayload | void = void> = ReturnType<
- typeof createLumberjack<TPayload>
->;
-
+/**
+ * Factory function that creates a Lumberjack core system object.
+ *
+ * @example
+ * const drivers = [new ConsoleDriver(), new HttpDriver()];
+ * const logFormatter = createLumberjackLogFormatter(deps);
+ *
+ * const lumberjack = createLumberjack({ drivers, logFormatter });
+ *
+ * const log = {
+ * scope: 'Application',
+ * createdAt: getUnixEpochTicks(),
+ * level: 'ERROR',
+ * message: 'An unexpected error occurred',
+ * };
+ *
+ * lumberjack.log(log);
+ */
 export function createLumberjack<TPayload extends LumberjackLogPayload | void = void>({
  drivers,
  logFormatter,

diff --git a/packages/webworker/lumberjack/src/lib/logging/lumberjack.ts b/packages/webworker/lumberjack/src/lib/logging/lumberjack.ts
@@ -0,0 +1,7 @@
+import { LumberjackLogPayload } from '../logs/lumberjack-log-payload';
+
+import { createLumberjack } from './create-lumberjack';
+
+export type Lumberjack<TPayload extends LumberjackLogPayload | void = void> = ReturnType<
+ typeof createLumberjack<TPayload>
+>;