Add in-code documentation

Author: dolfbarr

README.md

@@ -27,7 +27,7 @@
 React hook for logging per component lifecycle
 
 ## Features
-- 🪶 **Lightweight** — under *1Kb* gzipped
+- 🪶 **Lightweight** — under *1.5Kb* gzipped
 - 🗂️ **Typed** — made with TypeScript, ships with types
 - 🥰 **Simple** — don't worry about any changes in your props & state
 - 🔧 **Customizable** — work in progress 😉

package.json

@@ -106,11 +106,11 @@
   "size-limit": [
     {
       "path": "dist/main.js",
-      "limit": "1 kB"
+      "limit": "1.5 kB"
     },
     {
       "path": "dist/module.js",
-      "limit": "1 kB"
+      "limit": "1.5 kB"
     }
   ]
 }

src/constants.ts

@@ -0,0 +1,5 @@
+export const CSS_COMPONENT = 'color: DodgerBlue'
+export const CSS_CHANGE = 'color: green; font-weight: bold;'
+export const CSS_SUB_VALUE = 'color: SlateGray; font-weight: thin;'
+
+export const ALLOWED_NODE_ENVS = ['dev', 'development']

src/index.tsx

@@ -1,28 +1,68 @@
-import { useEffect, useRef } from 'react'
-import { UseLog, UseLogReturn, Log, PrintTypes, PrintProps } from './types'
-import { getComponentName, print } from './utils'
+// Copyright (c) Dolf Barr <[email protected]>. All rights reserved. Licensed under the MIT license.
 
-const CSS_COMPONENT = 'color: DodgerBlue'
-const CSS_CHANGE = 'color: green; font-weight: bold;'
-const CSS_SUB_VALUE = 'color: SlateGray; font-weight: thin;'
+/**
+ * A react hook for logging through component lifecycle.
+ *
+ * @packageDocumentation
+ */
 
-const ALLOWED_NODE_ENVS = ['dev', 'development']
+import { useEffect, useRef } from 'react'
+import {
+  ALLOWED_NODE_ENVS,
+  CSS_CHANGE,
+  CSS_COMPONENT,
+  CSS_SUB_VALUE,
+} from './constants'
+import {
+  UseLogConfig,
+  UseLogReturn,
+  LogConfig,
+  _PrintTypes,
+  _PrintConfig,
+} from './types'
+import { getComponentName, print } from './utils'
 
+/**
+ * Provides a function to log through react component lifecycle.
+ *
+ * @param config - component level configuration for any log function in the component
+ * @see {@link UseLogConfig} for the config data structure
+ *
+ * @returns set of functions suitable for logging
+ *
+ * @example
+ * ```ts
+ * const {log} = useLog({environments: ['dev']})
+ * ```
+ */
 export function useLog({
   styles: {
     componentCSS = CSS_COMPONENT,
     changeCSS = CSS_CHANGE,
     subValueCSS = CSS_SUB_VALUE,
   } = {},
   environments = ALLOWED_NODE_ENVS,
-}: UseLog = {}): UseLogReturn {
+}: UseLogConfig = {}): UseLogReturn {
   const componentName = getComponentName()
 
-  function log<T>(value: T, props?: Log): void {
+  /**
+   * Logging function to log through react component lifecycle.
+   *
+   * @param value - a value which changes will be logged
+   * @typeParam T - type of the tracking value
+   * @param config - component level configuration for any log function in the component
+   * @see {@link LogConfig} for the config data structure
+   *
+   * @example
+   * ```ts
+   * log(someState, {environments: ['production']})
+   * ```
+   */
+  function log<T>(value: T, props?: LogConfig): void {
     const clonedValue = JSON.parse(JSON.stringify(value)) as T
     const prevValueRef = useRef<T>()
     const printProps: Pick<
-      PrintProps<T>,
+      _PrintConfig<T>,
       'value' | 'styles' | 'componentName'
     > = {
       value: clonedValue,
@@ -37,6 +77,7 @@ export function useLog({
     if (environments.includes(process.env.NODE_ENV ?? 'production')) {
       function logHooks(): void {
         const isUnmounting = useRef(false)
+
         useEffect(function setIsUnmounting() {
           return function setIsUnmountingOnMount() {
             isUnmounting.current = true
@@ -46,7 +87,7 @@ export function useLog({
         useEffect(function onMount() {
           print({
             label: 'On mount',
-            type: PrintTypes.Mount,
+            type: _PrintTypes.Mount,
             ...printProps,
           })
 
@@ -55,7 +96,7 @@ export function useLog({
           return function onUnmount() {
             print({
               label: 'On unmount',
-              type: PrintTypes.Unmount,
+              type: _PrintTypes.Unmount,
               prevValue: prevValueRef.current,
               ...printProps,
             })
@@ -66,7 +107,7 @@ export function useLog({
           function onChange() {
             print({
               label: 'On change',
-              type: PrintTypes.Change,
+              type: _PrintTypes.Change,
               prevValue: prevValueRef.current,
               ...printProps,
             })

src/types.ts

@@ -1,31 +1,77 @@
 export interface Styles {
+  /**
+   * Inline css for rendering component name in the logs
+   *
+   * @defaultValue Blue text color
+   *
+   * @example
+   * ```css
+   * color:green;font-weight:bold;background-color:black;
+   * ```
+   */
   componentCSS?: string
+  /**
+   * Inline css for rendering current value in the logs
+   *
+   * @defaultValue Green text color with bold font
+   *
+   * @example
+   * ```css
+   * color:green;font-weight:bold;background-color:black;
+   * ```
+   */
   changeCSS?: string
+  /**
+   * Inline css for rendering any additional data like time or previous value in the logs
+   *
+   * @defaultValue Gray text color with thin font
+   *
+   * @example
+   * ```css
+   * color:green;font-weight:bold;background-color:black;
+   * ```
+   */
   subValueCSS?: string
 }
 
-export interface UseLog {
+/** Describes configuration object at component level */
+export interface UseLogConfig {
+  /** Contains styles object with different CSS inline styles used in logging */
   styles?: Styles
+  /** Contains array of environments of `process.env.NODE_ENV` in which logging will be allowed  */
   environments?: string[]
 }
 
-export type Log = UseLog
+/** Describes configuration object at call level, can be used to override configuration */
+export type LogConfig = UseLogConfig
 
+/** Return value of `useLog` hook */
 export interface UseLogReturn {
-  log: <T>(value: T, props?: Log) => void
+  /** Used for logging per component lifecycle */
+  log: <T>(value: T, props?: LogConfig) => void
 }
 
-export interface PrintProps<T> {
+/**
+ * Describes configuration object of the inner print function
+ * @internal
+ *
+ * @typeParam T - type of the tracking value
+ */
+export interface _PrintConfig<T> {
   value: T
   prevValue?: T
   label: string
   group?: string
-  type?: PrintTypes
+  type?: _PrintTypes
   styles?: Styles
   componentName: string
 }
 
-export enum PrintTypes {
+/**
+ * Label types of print groups
+ * @internal
+ */
+export enum _PrintTypes {
   Mount = 'Mount',
   Unmount = 'Unmount',
   Change = 'Change',

src/utils.test.ts

@@ -1,16 +1,16 @@
 import { getGroupLabel, getComponentName, print } from './utils'
-import { PrintProps, PrintTypes } from './types'
+import { _PrintConfig, _PrintTypes } from './types'
 
 describe('utils', () => {
   describe('getGroupLabel', () => {
     it('renders', () => {
-      expect(getGroupLabel(PrintTypes.Change)).toEqual(
+      expect(getGroupLabel(_PrintTypes.Change)).toEqual(
         `Change %c%c@ ${new Date().toLocaleTimeString()}`,
       )
     })
 
     it('renders with component name', () => {
-      expect(getGroupLabel(PrintTypes.Mount, 'TestComponent')).toEqual(
+      expect(getGroupLabel(_PrintTypes.Mount, 'TestComponent')).toEqual(
         `Mount in %c<TestComponent /> %c@ ${new Date().toLocaleTimeString()}`,
       )
     })
@@ -31,7 +31,7 @@ describe('utils', () => {
       .spyOn(console, 'groupEnd')
       .mockImplementation(() => null)
 
-    const printProps: PrintProps<string> = {
+    const printProps: _PrintConfig<string> = {
       value: 'Test Value',
       label: 'A Label',
       componentName: 'SomeComponentName',

src/utils.ts

@@ -1,7 +1,7 @@
-import { PrintProps, PrintTypes } from './types'
+import { _PrintConfig, _PrintTypes } from './types'
 
 export function getGroupLabel(
-  type: PrintTypes,
+  type: _PrintTypes,
   componentName?: string,
 ): string {
   return `${String(type)} ${
@@ -35,10 +35,10 @@ export function print<T>({
   label,
   prevValue,
   componentName,
-  type = PrintTypes.Change,
+  type = _PrintTypes.Change,
   group = getGroupLabel(type, componentName),
   styles: { componentCSS, subValueCSS, changeCSS } = {},
-}: PrintProps<T>): void {
+}: _PrintConfig<T>): void {
   console.group(group, componentCSS, subValueCSS)
 
   if (!('prevValue' in arguments[0])) {