From 9c5c2af86e33b516d421cdae664bb47ae602a923 Mon Sep 17 00:00:00 2001
From: aakhtar3 <aakhtar3@users.noreply.github.com>
Date: Thu, 1 Oct 2020 05:40:40 -0400
Subject: [PATCH] docs(uuid): Added JSdocs for the uuid module
 (denoland/deno#7735)

---
 uuid/_common.ts | 16 ++++++++++++++++
 uuid/mod.ts     |  7 ++++++-
 uuid/v1.ts      | 10 ++++++++++
 uuid/v4.ts      |  5 +++++
 uuid/v5.ts      | 10 ++++++++++
 5 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/uuid/_common.ts b/uuid/_common.ts
index 8f13ac7e3295..ef0bb42be71b 100644
--- a/uuid/_common.ts
+++ b/uuid/_common.ts
@@ -1,4 +1,8 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+/**
+ * Converts the byte array to a UUID string
+ * @param bytes Used to convert Byte to Hex
+ */
 export function bytesToUuid(bytes: number[] | Uint8Array): string {
   const bits: string[] = [...bytes].map((bit): string => {
     const s: string = bit.toString(16);
@@ -17,6 +21,10 @@ export function bytesToUuid(bytes: number[] | Uint8Array): string {
   ].join("");
 }
 
+/**
+ * Converts a string to a byte array by converting the hex value to a number
+ * @param uuid Value that gets converted
+ */
 export function uuidToBytes(uuid: string): number[] {
   const bytes: number[] = [];
 
@@ -28,6 +36,10 @@ export function uuidToBytes(uuid: string): number[] {
   return bytes;
 }
 
+/**
+ * Converts a string to a byte array using the char code
+ * @param str Value that gets converted
+ */
 export function stringToBytes(str: string): number[] {
   str = unescape(encodeURIComponent(str));
   const bytes = new Array(str.length);
@@ -37,6 +49,10 @@ export function stringToBytes(str: string): number[] {
   return bytes;
 }
 
+/**
+ * Creates a buffer for creating a SHA-1 hash
+ * @param content Buffer for SHA-1 hash
+ */
 export function createBuffer(content: number[]): ArrayBuffer {
   const arrayBuffer = new ArrayBuffer(content.length);
   const uint8Array = new Uint8Array(arrayBuffer);
diff --git a/uuid/mod.ts b/uuid/mod.ts
index 61b10e895c45..ff20fa807f36 100644
--- a/uuid/mod.ts
+++ b/uuid/mod.ts
@@ -1,4 +1,5 @@
-// Based on https://github.com/kelektiv/node-uuid
+// Based on https://github.com/kelektiv/node-uuid -> https://www.ietf.org/rfc/rfc4122.txt
+// Supporting Support for RFC4122 version 1, 4, and 5 UUIDs
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import * as v1 from "./v1.ts";
 import * as v4 from "./v4.ts";
@@ -6,6 +7,10 @@ import * as v5 from "./v5.ts";
 
 export const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 
+/**
+ * Checks if UUID is nil
+ * @param val UUID value
+ */
 export function isNil(val: string): boolean {
   return val === NIL_UUID;
 }
diff --git a/uuid/v1.ts b/uuid/v1.ts
index ef1882d85323..4adb0d6f92f4 100644
--- a/uuid/v1.ts
+++ b/uuid/v1.ts
@@ -6,6 +6,10 @@ const UUID_RE = new RegExp(
   "i",
 );
 
+/**
+ * Validates the UUID v1
+ * @param id UUID value
+ */
 export function validate(id: string): boolean {
   return UUID_RE.test(id);
 }
@@ -25,6 +29,12 @@ type V1Options = {
   rng?: () => number[];
 };
 
+/**
+ * Generates a RFC4122 v1 UUID (time-based)
+ * @param options Can use RFC time sequence values as overwrites
+ * @param buf Can allow the UUID to be written in byte-form starting at the offset
+ * @param offset Index to start writing on the UUID bytes in buffer
+ */
 export function generate(
   options?: V1Options | null,
   buf?: number[],
diff --git a/uuid/v4.ts b/uuid/v4.ts
index f338440f56fb..1245f2678c24 100644
--- a/uuid/v4.ts
+++ b/uuid/v4.ts
@@ -6,10 +6,15 @@ const UUID_RE = new RegExp(
   "i",
 );
 
+/**
+ * Validates the UUID v4
+ * @param id UUID value
+ */
 export function validate(id: string): boolean {
   return UUID_RE.test(id);
 }
 
+/** Generates a RFC4122 v4 UUID (pseudo-randomly-based) */
 export function generate(): string {
   const rnds = crypto.getRandomValues(new Uint8Array(16));
 
diff --git a/uuid/v5.ts b/uuid/v5.ts
index 9b4c4111adfc..64c131c5a147 100644
--- a/uuid/v5.ts
+++ b/uuid/v5.ts
@@ -11,6 +11,10 @@ import { assert } from "../_util/assert.ts";
 const UUID_RE =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
+/**
+ * Validates the UUID v5
+ * @param id UUID value
+ */
 export function validate(id: string): boolean {
   return UUID_RE.test(id);
 }
@@ -20,6 +24,12 @@ interface V5Options {
   namespace: string | number[];
 }
 
+/**
+ * Generates a RFC4122 v5 UUID (SHA-1 namespace-based)
+ * @param options Can use a namespace and value to creat SHA-1 hash
+ * @param buf Can allow the UUID to be written in byte-form starting at the offset
+ * @param offset Index to start writing on the UUID bytes in buffer
+ */
 export function generate(
   options: V5Options,
   buf?: number[],