From b3ea65ba5774209deeed87d7d18f8d8fc9b2a10d Mon Sep 17 00:00:00 2001
From: Max <maximogarciamtnez@gmail.com>
Date: Tue, 9 Apr 2024 21:25:20 +0200
Subject: [PATCH] docs: added and improved jsdocs (#6)

---
 src/encode.ts | 14 ++++++++++++++
 src/render.ts | 15 ++++++++++++---
 src/svg.ts    |  6 +++++-
 src/types.ts  |  9 +++++++++
 4 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/src/encode.ts b/src/encode.ts
index b9e1ee1..770baa2 100644
--- a/src/encode.ts
+++ b/src/encode.ts
@@ -6,6 +6,12 @@ import {
 } from './qrcode'
 import { QrCodeDataType, type QrCodeGenerateData, type QrCodeGenerateOptions, type QrCodeGenerateResult } from './types'
 
+/**
+ * Encodes the given data into a QR code format according to the given options.
+ * @param {QrCodeGenerateData} data - The data to encode, either as a string or an array of bytes. See {@link QrCodeGenerateData}.
+ * @param {QrCodeGenerateOptions} [options] - QR Code generation configuration options. Optional. See {@link QrCodeGenerateOptions}.
+ * @returns {QrCodeGenerateResult} The result of the QR code generation, including the QR code matrix. See {@link QrCodeGenerateResult}.
+ */
 export function encode(data: QrCodeGenerateData, options?: QrCodeGenerateOptions): QrCodeGenerateResult {
   const {
     ecc = 'L',
@@ -85,6 +91,14 @@ function addBorder(input: QrCodeGenerateResult, border = 1): QrCodeGenerateResul
   return input
 }
 
+/**
+ * Returns the data value at a given coordinate in the QR code matrix.
+ * @param {boolean[][]} data - The QR code data matrix.
+ * @param {number} x - The x coordinate (column index) within the matrix.
+ * @param {number} y - The y coordinate (row index) within the matrix.
+ * @param {boolean} [defaults=false] - The default value to return if the coordinates are out of bounds. Optional.
+ * @returns {boolean} The data value at the given coordinate or the default value if out of bounds.
+ */
 export function getDataAt(data: boolean[][], x: number, y: number, defaults = false) {
   if (x < 0 || y < 0 || x >= data.length || y >= data.length)
     return defaults
diff --git a/src/render.ts b/src/render.ts
index b695a6e..a20954a 100644
--- a/src/render.ts
+++ b/src/render.ts
@@ -2,7 +2,10 @@ import type { QrCodeGenerateData, QrCodeGenerateOptions, QrCodeGenerateUnicodeOp
 import { encode, getDataAt } from './encode'
 
 /**
- * Render QR Code with unicode `█`, `░`
+ * Renders a QR code as a string using the specified Unicode characters for dark(`█`) and light(`░`) modules.
+ * @param {QrCodeGenerateData} data - The data to encode into the QR code. See {@link QrCodeGenerateData}.
+ * @param {QrCodeGenerateUnicodeOptions} [options={}] - Rendering options, including characters for white and black modules. optional. See {@link QrCodeGenerateUnicodeOptions}.
+ * Returns {string} A string representing the QR code, with each module replaced by the specified Unicode character.
  */
 export function renderUnicode(
   data: QrCodeGenerateData,
@@ -20,7 +23,10 @@ export function renderUnicode(
 }
 
 /**
- * Render QR Code with ANSI color for terminal
+ * Renders a QR code as a string suitable for display on terminals using ANSI background colours.
+ * @param {QrCodeGenerateData} data - The data to encode into the QR code. See {@link QrCodeGenerateData}.
+ * @param {QrCodeGenerateOptions} [options={}] - Options to render the QR code. optional. See {@link QrCodeGenerateOptions}.
+ * @returns {string} A string representing the QR code using ANSI colours, formatted for terminal display.
  */
 export function renderANSI(
   data: QrCodeGenerateData,
@@ -34,7 +40,10 @@ export function renderANSI(
 }
 
 /**
- * Render QR Code with two rows into one line with unicode `▀`, `▄`, `█`, ` `
+ * Renders a QR code as a compact string using a combination of top half block(`▀`), bottom half block(`▄`), full block(`█`) and spaces to represent two lines in a single line.
+ * @param {QrCodeGenerateData} data - The data to encode into the QR code. See {@link QrCodeGenerateData}.
+ * @param {QrCodeGenerateOptions} [options={}] - Options to render the QR code in a compact form. optional. See {@link QrCodeGenerateOptions}.
+ * @returns {string} A string representing the QR code in a compact format, using Unicode block characters to combine two lines per line.
  */
 export function renderUnicodeCompact(
   data: QrCodeGenerateData,
diff --git a/src/svg.ts b/src/svg.ts
index dbd7d87..0f8ea3b 100644
--- a/src/svg.ts
+++ b/src/svg.ts
@@ -2,7 +2,11 @@ import { encode } from './encode'
 import type { QrCodeGenerateData, QrCodeGenerateSvgOptions } from './types'
 
 /**
- * Render QR Code as SVG string
+ * Renders a QR code as an SVG string.
+ * The function converts the input data into a QR code and then generates an SVG representation using the specified colours and pixel sizes.
+ * @param {QrCodeGenerateData} data - The data to encode into the QR code. See {@link QrCodeGenerateData}.
+ * @param {QrCodeGenerateSvgOptions} [options={}] - Options to render the QR code in SVG format, including pixel size and colours for modules. optional. See {@link QrCodeGenerateSvgOptions}.
+ * @returns {string} An SVG string representing the QR code.
  */
 export function renderSVG(
   data: QrCodeGenerateData,
diff --git a/src/types.ts b/src/types.ts
index 1e405a0..f7f0ddc 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -89,11 +89,20 @@ export interface QrCodeGenerateResult {
 }
 
 export interface QrCodeGenerateInvertableOptions extends QrCodeGenerateOptions {
+  /**
+   * Adds the option to invert the colour scheme of the QR code in addition to the standard options.
+   */
   invert?: boolean
 }
 
 export interface QrCodeGenerateUnicodeOptions extends QrCodeGenerateInvertableOptions {
+  /**
+   * Character used to represent white modules in the QR code.
+   */
   whiteChar?: string
+  /**
+   * Character used to represent black modules in the QR code.
+   */
   blackChar?: string
 }