chore: updating doc comments for RPC message types

[ci skip]

Author: tegefaulkes

src/rpc/types.ts

@@ -18,82 +18,140 @@ import type { POJO } from '../types';
  * This is the JSON RPC request object. this is the generic message type used for the RPC.
  */
 type JSONRPCRequestMessage<T extends JSONValue = JSONValue> = {
-  // A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0"
+  /**
+   * A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0"
+   */
   jsonrpc: '2.0';
-  // A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a
-  //  period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used
-  //  for anything else.
+  /**
+   * A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a
+   *  period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used
+   *  for anything else.
+   */
   method: string;
-  // A Structured value that holds the parameter values to be used during the invocation of the method.
-  //  This member MAY be omitted.
+  /**
+   * A Structured value that holds the parameter values to be used during the invocation of the method.
+   *  This member MAY be omitted.
+   */
   params?: T;
-  // An identifier established by the Client that MUST contain a String, Number, or NULL value if included.
-  //  If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers
-  //  SHOULD NOT contain fractional parts [2]
+  /**
+   * An identifier established by the Client that MUST contain a String, Number, or NULL value if included.
+   *  If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers
+   *  SHOULD NOT contain fractional parts [2]
+   */
   id: string | number | null;
 };
 
+/**
+ * This is the JSON RPC notification object. this is used for a request that
+ * doesn't expect a response.
+ */
 type JSONRPCRequestNotification<T extends JSONValue = JSONValue> = {
-  // A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0"
+  /**
+   * A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0"
+   */
   jsonrpc: '2.0';
-  // A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a
-  //  period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used
-  //  for anything else.
+  /**
+   * A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a
+   *  period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used
+   *  for anything else.
+   */
   method: string;
-  // A Structured value that holds the parameter values to be used during the invocation of the method.
-  //  This member MAY be omitted.
+  /**
+   * A Structured value that holds the parameter values to be used during the invocation of the method.
+   *  This member MAY be omitted.
+   */
   params?: T;
 };
 
+/**
+ * This is the JSON RPC response result object. It contains the response data for a
+ * corresponding request.
+ */
 type JSONRPCResponseResult<T extends JSONValue = JSONValue> = {
-  // A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
+  /**
+   * A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
+   */
   jsonrpc: '2.0';
-  // This member is REQUIRED on success.
-  //  This member MUST NOT exist if there was an error invoking the method.
-  //  The value of this member is determined by the method invoked on the Server.
+  /**
+   * This member is REQUIRED on success.
+   *  This member MUST NOT exist if there was an error invoking the method.
+   *  The value of this member is determined by the method invoked on the Server.
+   */
   result: T;
-  // This member is REQUIRED.
-  //  It MUST be the same as the value of the id member in the Request Object.
-  //  If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request),
-  //  it MUST be Null.
+  /**
+   * This member is REQUIRED.
+   *  It MUST be the same as the value of the id member in the Request Object.
+   *  If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request),
+   *  it MUST be Null.
+   */
   id: string | number | null;
 };
 
+/**
+ * This is the JSON RPC response Error object. It contains any errors that have
+ * occurred when responding to a request.
+ */
 type JSONRPCResponseError = {
-  // A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
+  /**
+   * A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
+   */
   jsonrpc: '2.0';
-  // This member is REQUIRED on error.
-  //  This member MUST NOT exist if there was no error triggered during invocation.
-  //  The value for this member MUST be an Object as defined in section 5.1.
+  /**
+   * This member is REQUIRED on error.
+   *  This member MUST NOT exist if there was no error triggered during invocation.
+   *  The value for this member MUST be an Object as defined in section 5.1.
+   */
   error: JSONRPCError;
-  // This member is REQUIRED.
-  //  It MUST be the same as the value of the id member in the Request Object.
-  //  If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request),
-  //  it MUST be Null.
+  /**
+   * This member is REQUIRED.
+   *  It MUST be the same as the value of the id member in the Request Object.
+   *  If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request),
+   *  it MUST be Null.
+   */
   id: string | number | null;
 };
 
+/**
+ * This is a JSON RPC error object, it encodes the error data for the JSONRPCResponseError object.
+ */
 type JSONRPCError = {
-  // A Number that indicates the error type that occurred.
-  //  This MUST be an integer.
+  /**
+   * A Number that indicates the error type that occurred.
+   *  This MUST be an integer.
+   */
   code: number;
-  // A String providing a short description of the error.
-  //  The message SHOULD be limited to a concise single sentence.
+  /**
+   * A String providing a short description of the error.
+   *  The message SHOULD be limited to a concise single sentence.
+   */
   message: string;
-  // A Primitive or Structured value that contains additional information about the error.
-  //  This may be omitted.
-  //  The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).
+  /**
+   * A Primitive or Structured value that contains additional information about the error.
+   *  This may be omitted.
+   *  The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).
+   */
   data?: JSONValue;
 };
 
+/**
+ * This is the JSON RPC Request object. It can be a request message or
+ * notification.
+ */
 type JSONRPCRequest<T extends JSONValue = JSONValue> =
   | JSONRPCRequestMessage<T>
   | JSONRPCRequestNotification<T>;
 
+/**
+ * This is a JSON RPC response object. It can be a response result or error.
+ */
 type JSONRPCResponse<T extends JSONValue = JSONValue> =
   | JSONRPCResponseResult<T>
   | JSONRPCResponseError;
 
+/**
+ * This is a JSON RPC Message object. This is top level and can be any kind of
+ * message.
+ */
 type JSONRPCMessage<T extends JSONValue = JSONValue> =
   | JSONRPCRequest<T>
   | JSONRPCResponse<T>;