From f85963dfb87e38b9bbf2356c6b81d88e72da29e9 Mon Sep 17 00:00:00 2001
From: Andrea Carraro <me@andreacarraro.it>
Date: Wed, 15 May 2024 10:59:17 +0200
Subject: [PATCH] refactor: minor commment improvements

---
 src/openapiToTsJsonSchema.ts                              | 8 ++++++--
 src/utils/convertOpenApiToJsonSchema.ts                   | 8 ++++----
 .../replaceInlinedRefsWithStringPlaceholder.ts            | 4 ++--
 .../replacePlaceholdersWithImportedSchemas.ts             | 2 +-
 src/utils/makeTsJsonSchema/replacePlaceholdersWithRefs.ts | 2 +-
 5 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/src/openapiToTsJsonSchema.ts b/src/openapiToTsJsonSchema.ts
index fec1954..6033e38 100644
--- a/src/openapiToTsJsonSchema.ts
+++ b/src/openapiToTsJsonSchema.ts
@@ -75,10 +75,14 @@ export async function openapiToTsJsonSchema(
 
   const openApiParser = new $RefParser();
   const jsonSchemaParser = new $RefParser();
+
+  // Resolve and inline external $ref definitions
   const bundledOpenApiSchema = await openApiParser.bundle(openApiSchemaPath);
+  // Convert oas definitions to JSON schema
   const initialJsonSchema = convertOpenApiToJsonSchema(bundledOpenApiSchema);
 
   const inlinedRefs: Map<string, JSONSchema> = new Map();
+  // Inline and collect internal $ref definitions
   const dereferencedJsonSchema = await jsonSchemaParser.dereference(
     initialJsonSchema,
     {
@@ -97,8 +101,8 @@ export async function openapiToTsJsonSchema(
           }
 
           /**
-           * mark inlined ref objects with a "SCHEMA_ID_SYMBOL" to retrieve their
-           * original $ref value once inlined
+           * mark inlined ref objects with a "SCHEMA_ID_SYMBOL"
+           * to retrieve their id once inlined
            */
           inlinedSchema[SCHEMA_ID_SYMBOL] = id;
 
diff --git a/src/utils/convertOpenApiToJsonSchema.ts b/src/utils/convertOpenApiToJsonSchema.ts
index b5b0c0c..c99fe24 100644
--- a/src/utils/convertOpenApiToJsonSchema.ts
+++ b/src/utils/convertOpenApiToJsonSchema.ts
@@ -36,11 +36,11 @@ function convertToJsonSchema<Value extends unknown>(
 }
 
 /**
- * Traverse the openAPI schema tree an brutally try to convert everything
- * possible to JSON schema. We are probably overdoing since we process any object we find.
+ * Traverse the openAPI schema tree an brutally try to convert every oas definition
+ * to JSON schema. We are probably overdoing since we process any found object.
  *
- * - Is there a way to tell an OpenAPI schema objects convertible to JSON schema from the others?
- * - Could we explicitly convert only the properties where we know conversion is needed?
+ * - Is there a way to tell an OpenAPI definition objects convertible to JSON schema from the others?
+ * - Could we explicitly convert only the properties that need it?
  *
  * @TODO Find a nicer way to convert convert all the expected OpenAPI schemas
  */
diff --git a/src/utils/makeTsJsonSchema/replaceInlinedRefsWithStringPlaceholder.ts b/src/utils/makeTsJsonSchema/replaceInlinedRefsWithStringPlaceholder.ts
index 935a575..b9f3390 100644
--- a/src/utils/makeTsJsonSchema/replaceInlinedRefsWithStringPlaceholder.ts
+++ b/src/utils/makeTsJsonSchema/replaceInlinedRefsWithStringPlaceholder.ts
@@ -5,7 +5,7 @@ import type { JSONSchema, JSONSchemaWithPlaceholders } from '../../types';
 
 /**
  * Get any JSON schema node and:
- * - Return ref placeholder is the entity is an inlined ref schema objects (with SCHEMA_ID_SYMBOL prop)
+ * - Return id placeholder if the entity is an inlined ref schema objects (with SCHEMA_ID_SYMBOL prop)
  * - Return provided node in all other cases
  */
 function replaceInlinedSchemaWithPlaceholder<Node extends unknown>(
@@ -21,7 +21,7 @@ function replaceInlinedSchemaWithPlaceholder<Node extends unknown>(
 /**
  * Iterate a JSON schema to replace inlined ref schema objects
  * (marked with a SCHEMA_ID_SYMBOL property holding the original $ref value)
- * with a string placeholder with a reference to the original $ref value ("_OTJS-START_/id/value_OTJS-END_")
+ * with a string placeholder with a reference to their internal id ("_OTJS-START_/id/value_OTJS-END_")
  */
 export function replaceInlinedRefsWithStringPlaceholder(
   schema: JSONSchema,
diff --git a/src/utils/makeTsJsonSchema/replacePlaceholdersWithImportedSchemas.ts b/src/utils/makeTsJsonSchema/replacePlaceholdersWithImportedSchemas.ts
index 459c174..0153159 100644
--- a/src/utils/makeTsJsonSchema/replacePlaceholdersWithImportedSchemas.ts
+++ b/src/utils/makeTsJsonSchema/replacePlaceholdersWithImportedSchemas.ts
@@ -2,7 +2,7 @@ import { makeRelativeModulePath, PLACEHOLDER_REGEX } from '..';
 import type { SchemaMetaDataMap } from '../../types';
 
 /**
- * Replace Refs placeholders with imported schemas
+ * Replace id placeholders with imported schemas
  */
 export function replacePlaceholdersWithImportedSchemas({
   schemaAsText,
diff --git a/src/utils/makeTsJsonSchema/replacePlaceholdersWithRefs.ts b/src/utils/makeTsJsonSchema/replacePlaceholdersWithRefs.ts
index 65d3923..7fae360 100644
--- a/src/utils/makeTsJsonSchema/replacePlaceholdersWithRefs.ts
+++ b/src/utils/makeTsJsonSchema/replacePlaceholdersWithRefs.ts
@@ -1,7 +1,7 @@
 import { PLACEHOLDER_REGEX } from '..';
 
 /**
- * Replace Refs placeholders with original ref objects
+ * Replace id placeholders with their relevant $ref object
  */
 export function replacePlaceholdersWithRefs({
   schemaAsText,