From 9d02b3f7dd7247537fc680b1ce26799eb2fc529a Mon Sep 17 00:00:00 2001
From: Nilay Majorwar <nilaymajorwar@gmail.com>
Date: Mon, 31 Jan 2022 18:54:30 +0530
Subject: [PATCH] Improve docs for language utils

---
 languages/types.ts         | 14 +++++++++-----
 languages/worker-errors.ts | 30 ++++++++++++++++++++++++------
 2 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/languages/types.ts b/languages/types.ts
index 0972133..24942f6 100644
--- a/languages/types.ts
+++ b/languages/types.ts
@@ -2,15 +2,19 @@ import monaco from "monaco-editor";
 import React from "react";
 
 /**
- * Type alias for defining range of characters to highlight in a single line.
- * - Missing `start` means highlight starting from start of the line.
- * - Missing `end` means highlight ending at the end of the line.
+ * Type alias for defining range of characters in a single line.
+ * - Missing `start` means range starting from start of the line.
+ * - Missing `end` means range ending at the end of the line.
  */
 export type CharRange = { start?: number; end?: number };
 
-/** Type denoting a range of text in document spanning within a line */
+/**
+ * Type denoting a range of text in document spanning within a line.
+ */
 export type DocumentRange = {
+  /** Line number of the range */
   line: number;
+  /** Section of line - omit to cover entire line */
   charRange?: CharRange;
 };
 
@@ -47,7 +51,7 @@ export type StepExecutionResult<RS> = {
    */
   nextStepLocation: DocumentRange | null;
 
-  /** Signal if execution has been paused/stopped */
+  /** Signal if execution has been paused */
   signal?: "paused";
 };
 
diff --git a/languages/worker-errors.ts b/languages/worker-errors.ts
index 687be9a..a6937dd 100644
--- a/languages/worker-errors.ts
+++ b/languages/worker-errors.ts
@@ -45,39 +45,57 @@ export const isRuntimeError = (error: any): error is RuntimeError => {
   return error instanceof RuntimeError || error.name === "RuntimeError";
 };
 
-/** Error sent by worker in case of parsing error */
+/**
+ * Error sent by worker in case of parsing error.
+ * Not for use by language providers.
+ */
 export type WorkerParseError = {
   name: "ParseError";
   message: string;
   range: DocumentRange;
 };
 
-/** Error sent by worker in case error at runtime */
+/**
+ * Error sent by worker in case error at runtime.
+ * Not for use by language providers.
+ */
 export type WorkerRuntimeError = {
   name: "RuntimeError";
   message: string;
 };
 
-/** Error sent by worker indicating an implementation bug */
+/**
+ * Error sent by worker indicating an implementation bug.
+ * Not for use by language providers.
+ */
 export type WorkerError = {
   name: string;
   message: string;
   stack?: string;
 };
 
-/** Serialize a RuntimeError instance into a plain object */
+/**
+ * Serialize a RuntimeError instance into a plain object.
+ * Not for use by language providers.
+ */
 export const serializeRuntimeError = (
   error: RuntimeError
 ): WorkerRuntimeError => {
   return { name: "RuntimeError", message: error.message };
 };
 
-/** Serialize a ParseError instance into a plain object */
+/**
+ * Serialize a ParseError instance into a plain object.
+ * Not for use by language providers.
+ */
 export const serializeParseError = (error: ParseError): WorkerParseError => {
   return { name: "ParseError", message: error.message, range: error.range };
 };
 
-/** Serialize an arbitrary error into a plain object */
+/**
+ * Serialize an arbitrary error into a plain object.
+ * Not for use by language providers.
+ */
 export const serializeError = (error: Error): WorkerError => {
   return { name: error.name, message: error.message, stack: error.stack };
 };