From 8310269c92e8b7c5afeec30636f255dd6f11725a Mon Sep 17 00:00:00 2001
From: Daniel Dyla <dyladan@users.noreply.github.com>
Date: Wed, 6 Jan 2021 11:45:49 -0500
Subject: [PATCH] chore: add jsdocs to semver functions

---
 .../opentelemetry-api/src/internal/semver.ts  | 41 ++++++++++++++-----
 1 file changed, 31 insertions(+), 10 deletions(-)

diff --git a/packages/opentelemetry-api/src/internal/semver.ts b/packages/opentelemetry-api/src/internal/semver.ts
index 52e2ebc401..fba640d4eb 100644
--- a/packages/opentelemetry-api/src/internal/semver.ts
+++ b/packages/opentelemetry-api/src/internal/semver.ts
@@ -18,18 +18,29 @@ import { VERSION } from '../version';
 
 const re = /^(\d+)\.(\d+)\.(\d+)(?:-(.*))?$/;
 
+/**
+ * Create a function to test an API version to see if it is compatible with the provided ownVersion.
+ *
+ * The returned function has the following semantics:
+ * - Exact match is always compatible
+ * - Major versions must always match
+ * - The minor version of the API module requesting access to the global API must be greater or equal to the minor version of this API
+ * - Patch and build tag differences are not considered at this time
+ *
+ * @param ownVersion version which should be checked against
+ */
 export function _makeCompatibilityCheck(
-  myVersion: string
+  ownVersion: string
 ): (version: string) => boolean {
-  const acceptedVersions = new Set<string>([myVersion]);
+  const acceptedVersions = new Set<string>([ownVersion]);
   const rejectedVersions = new Set<string>();
 
-  const myVersionMatch = myVersion.match(re);
+  const myVersionMatch = ownVersion.match(re);
   if (!myVersionMatch) {
     throw new Error('Cannot parse own version');
   }
 
-  const ownVersion = {
+  const ownVersionParsed = {
     major: +myVersionMatch[1],
     minor: +myVersionMatch[2],
     patch: +myVersionMatch[3],
@@ -51,26 +62,26 @@ export function _makeCompatibilityCheck(
       return false;
     }
 
-    const other = {
+    const otherVersionParsed = {
       major: +m[1],
       minor: +m[2],
       patch: +m[3],
     };
 
     // major versions must match
-    if (ownVersion.major != other.major) {
+    if (ownVersionParsed.major != otherVersionParsed.major) {
       rejectedVersions.add(version);
       return false;
     }
 
     // if major version is 0, minor is treated like major and patch is treated like minor
-    if (ownVersion.major === 0) {
-      if (ownVersion.minor != other.minor) {
+    if (ownVersionParsed.major === 0) {
+      if (ownVersionParsed.minor != otherVersionParsed.minor) {
         rejectedVersions.add(version);
         return false;
       }
 
-      if (ownVersion.patch < other.patch) {
+      if (ownVersionParsed.patch < otherVersionParsed.patch) {
         rejectedVersions.add(version);
         return false;
       }
@@ -79,7 +90,7 @@ export function _makeCompatibilityCheck(
       return true;
     }
 
-    if (ownVersion.minor < other.minor) {
+    if (ownVersionParsed.minor < otherVersionParsed.minor) {
       rejectedVersions.add(version);
       return false;
     }
@@ -89,4 +100,14 @@ export function _makeCompatibilityCheck(
   };
 }
 
+/**
+ * Test an API version to see if it is compatible with this API.
+ *
+ * - Exact match is always compatible
+ * - Major versions must always match
+ * - The minor version of the API module requesting access to the global API must be greater or equal to the minor version of this API
+ * - Patch and build tag differences are not considered at this time
+ *
+ * @param version version of the API requesting an instance of the global API
+ */
 export const isCompatible = _makeCompatibilityCheck(VERSION);