refactor: minor commment improvements

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;
 

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
  */

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,

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,

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,