enhance: Add docstrings to RestGenerics, ResourceGenerics, and RestEn…

…dpointOptions members
reactive · May 14, 2024 · bf1f9bb · bf1f9bb
1 parent 4bc9145
commit bf1f9bb
Show file tree

Hide file tree

Showing 5 changed files with 74 additions and 3 deletions.
diff --git a/.changeset/tricky-planets-serve.md b/.changeset/tricky-planets-serve.md
@@ -0,0 +1,5 @@
+---
+"@data-client/rest": patch
+---
+
+Add docstrings to RestGenerics, ResourceGenerics, and RestEndpointOptions members
diff --git a/packages/rest/src/RestEndpointTypes.ts b/packages/rest/src/RestEndpointTypes.ts
@@ -345,6 +345,10 @@ export interface PartialRestGenerics {
   /** @see https://dataclient.io/rest/api/RestEndpoint#process */
   process?(value: any, ...args: any): any;
 }
+/** Generic types when constructing a RestEndpoint
+ *
+ * @see https://dataclient.io/rest/api/RestEndpoint#inheritance
+ */
 export interface RestGenerics extends PartialRestGenerics {
   readonly path: string;
 }
@@ -410,11 +414,26 @@ export interface RestEndpointOptions<
   F extends FetchFunction = FetchFunction,
   S extends Schema | undefined = undefined,
 > extends EndpointExtraOptions<F> {
+  /** Prepended to all urls
+   * @see https://dataclient.io/rest/api/RestEndpoint#urlPrefix
+   */
   urlPrefix?: string;
   requestInit?: RequestInit;
+  /** Called by getRequestInit to determine HTTP Headers
+   * @see https://dataclient.io/rest/api/RestEndpoint#getHeaders
+   */
   getHeaders?(headers: HeadersInit): Promise<HeadersInit> | HeadersInit;
+  /** Prepares RequestInit used in fetch. This is sent to fetchResponse()
+   * @see https://dataclient.io/rest/api/RestEndpoint#getRequestInit
+   */
   getRequestInit?(body: any): Promise<RequestInit> | RequestInit;
+  /** Performs the fetch call
+   * @see https://dataclient.io/rest/api/RestEndpoint#fetchResponse
+   */
   fetchResponse?(input: RequestInfo, init: RequestInit): Promise<any>;
+  /** Takes the Response and parses via .text() or .json()
+   * @see https://dataclient.io/rest/api/RestEndpoint#parseResponse
+   */
   parseResponse?(response: Response): Promise<any>;
 
   sideEffect?: boolean | undefined;

diff --git a/packages/rest/src/resourceTypes.ts b/packages/rest/src/resourceTypes.ts
@@ -17,7 +17,10 @@ import RestEndpoint, {
   RestTypeNoBody,
 } from './RestEndpoint.js';
 
-/** The typed (generic) options for a Resource */
+/** The typed (generic) options for a Resource
+ *
+ * @see https://dataclient.io/rest/api/createResource#function-inheritance-patterns
+ */
 export interface ResourceGenerics {
   /** @see https://dataclient.io/rest/api/createResource#path */
   readonly path: ResourcePath;

diff --git a/website/src/components/Playground/editor-types/@data-client/rest.d.ts b/website/src/components/Playground/editor-types/@data-client/rest.d.ts
@@ -1350,6 +1350,10 @@ interface PartialRestGenerics {
     /** @see https://dataclient.io/rest/api/RestEndpoint#process */
     process?(value: any, ...args: any): any;
 }
+/** Generic types when constructing a RestEndpoint
+ *
+ * @see https://dataclient.io/rest/api/RestEndpoint#inheritance
+ */
 interface RestGenerics extends PartialRestGenerics {
     readonly path: string;
 }
@@ -1383,11 +1387,26 @@ type OptionsToAdderBodyArgument<O extends {
     body?: any;
 }> = 'body' extends keyof O ? O['body'] : any;
 interface RestEndpointOptions<F extends FetchFunction = FetchFunction, S extends Schema | undefined = undefined> extends EndpointExtraOptions<F> {
+    /** Prepended to all urls
+     * @see https://dataclient.io/rest/api/RestEndpoint#urlPrefix
+     */
     urlPrefix?: string;
     requestInit?: RequestInit;
+    /** Called by getRequestInit to determine HTTP Headers
+     * @see https://dataclient.io/rest/api/RestEndpoint#getHeaders
+     */
     getHeaders?(headers: HeadersInit): Promise<HeadersInit> | HeadersInit;
+    /** Prepares RequestInit used in fetch. This is sent to fetchResponse()
+     * @see https://dataclient.io/rest/api/RestEndpoint#getRequestInit
+     */
     getRequestInit?(body: any): Promise<RequestInit> | RequestInit;
+    /** Performs the fetch call
+     * @see https://dataclient.io/rest/api/RestEndpoint#fetchResponse
+     */
     fetchResponse?(input: RequestInfo, init: RequestInit): Promise<any>;
+    /** Takes the Response and parses via .text() or .json()
+     * @see https://dataclient.io/rest/api/RestEndpoint#parseResponse
+     */
     parseResponse?(response: Response): Promise<any>;
     sideEffect?: boolean | undefined;
     name?: string;
@@ -1548,7 +1567,10 @@ interface Extendable<O extends ResourceGenerics = {
     extend<R extends ResourceInterface, T extends Record<string, EndpointInterface>>(this: R, extender: (baseResource: R) => T): ExtendedResource<R, T>;
 }
 
-/** The typed (generic) options for a Resource */
+/** The typed (generic) options for a Resource
+ *
+ * @see https://dataclient.io/rest/api/createResource#function-inheritance-patterns
+ */
 interface ResourceGenerics {
     /** @see https://dataclient.io/rest/api/createResource#path */
     readonly path: ResourcePath;

diff --git a/website/src/components/Playground/editor-types/globals.d.ts b/website/src/components/Playground/editor-types/globals.d.ts
@@ -1354,6 +1354,10 @@ interface PartialRestGenerics {
     /** @see https://dataclient.io/rest/api/RestEndpoint#process */
     process?(value: any, ...args: any): any;
 }
+/** Generic types when constructing a RestEndpoint
+ *
+ * @see https://dataclient.io/rest/api/RestEndpoint#inheritance
+ */
 interface RestGenerics extends PartialRestGenerics {
     readonly path: string;
 }
@@ -1387,11 +1391,26 @@ type OptionsToAdderBodyArgument<O extends {
     body?: any;
 }> = 'body' extends keyof O ? O['body'] : any;
 interface RestEndpointOptions<F extends FetchFunction = FetchFunction, S extends Schema | undefined = undefined> extends EndpointExtraOptions<F> {
+    /** Prepended to all urls
+     * @see https://dataclient.io/rest/api/RestEndpoint#urlPrefix
+     */
     urlPrefix?: string;
     requestInit?: RequestInit;
+    /** Called by getRequestInit to determine HTTP Headers
+     * @see https://dataclient.io/rest/api/RestEndpoint#getHeaders
+     */
     getHeaders?(headers: HeadersInit): Promise<HeadersInit> | HeadersInit;
+    /** Prepares RequestInit used in fetch. This is sent to fetchResponse()
+     * @see https://dataclient.io/rest/api/RestEndpoint#getRequestInit
+     */
     getRequestInit?(body: any): Promise<RequestInit> | RequestInit;
+    /** Performs the fetch call
+     * @see https://dataclient.io/rest/api/RestEndpoint#fetchResponse
+     */
     fetchResponse?(input: RequestInfo, init: RequestInit): Promise<any>;
+    /** Takes the Response and parses via .text() or .json()
+     * @see https://dataclient.io/rest/api/RestEndpoint#parseResponse
+     */
     parseResponse?(response: Response): Promise<any>;
     sideEffect?: boolean | undefined;
     name?: string;
@@ -1552,7 +1571,10 @@ interface Extendable<O extends ResourceGenerics = {
     extend<R extends ResourceInterface, T extends Record<string, EndpointInterface>>(this: R, extender: (baseResource: R) => T): ExtendedResource<R, T>;
 }
 
-/** The typed (generic) options for a Resource */
+/** The typed (generic) options for a Resource
+ *
+ * @see https://dataclient.io/rest/api/createResource#function-inheritance-patterns
+ */
 interface ResourceGenerics {
     /** @see https://dataclient.io/rest/api/createResource#path */
     readonly path: ResourcePath;