enhance: Improve clarity of Resource method docstrings

reactive · May 18, 2024 · 9c04770 · 9c04770
1 parent 67f0f1d
commit 9c04770
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 18 deletions.
diff --git a/.changeset/wicked-ways-yawn.md b/.changeset/wicked-ways-yawn.md
@@ -0,0 +1,5 @@
+---
+"@data-client/rest": patch
+---
+
+Improve clarity of Resource method docstrings
diff --git a/packages/rest/src/RestEndpointTypes.ts b/packages/rest/src/RestEndpointTypes.ts
@@ -139,7 +139,7 @@ export interface RestInstance<
     this: E,
     cursorField: C,
   ): PaginationFieldEndpoint<E, C>;
-  /** Endpoint to append the next page extending a list for pagination
+  /** Concatinate the next page of results (GET)
    * @see https://dataclient.io/rest/api/RestEndpoint#getPage
    */
   getPage: 'paginationField' extends keyof O ?
@@ -150,7 +150,7 @@ export interface RestInstance<
       >
     : undefined
   : undefined;
-  /** Endpoint that pushes (place at end) a newly created entity to this Collection
+  /** Create a new item (POST) and `push` to the end
    * @see https://dataclient.io/rest/api/RestEndpoint#push
    */
   push: AddEndpoint<
@@ -163,7 +163,7 @@ export interface RestInstance<
         | FormData;
     }
   >;
-  /** Endpoint that unshifts (place at start) a newly created entity to this Collection
+  /** Create a new item (POST) and `unshift` to the beginning
    * @see https://dataclient.io/rest/api/RestEndpoint#unshift
    */
   unshift: AddEndpoint<
@@ -176,7 +176,7 @@ export interface RestInstance<
         | FormData;
     }
   >;
-  /** Endpoint that assigns newly created entities to their respective keys in this Collection
+  /** Create new item(s) (POST) and `Object.assign` merge
    * @see https://dataclient.io/rest/api/RestEndpoint#assign
    */
   assign: AddEndpoint<

diff --git a/packages/rest/src/resourceTypes.ts b/packages/rest/src/resourceTypes.ts
@@ -68,12 +68,12 @@ export interface ResourceOptions {
 export interface Resource<
   O extends ResourceGenerics = { path: ResourcePath; schema: any },
 > extends Extendable<O> {
-  /** Get a singular item
+  /** Get one item (GET)
    *
    * @see https://dataclient.io/rest/api/createResource#get
    */
   get: GetEndpoint<{ path: O['path']; schema: O['schema'] }>;
-  /** Get a list of item
+  /** Get an Array of items (GET)
    *
    * @see https://dataclient.io/rest/api/createResource#getlist
    */

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
@@ -1263,26 +1263,26 @@ interface RestInstance<F extends FetchFunction = FetchFunction, S extends Schema
      */
     paginated<E extends RestInstanceBase<FetchFunction, any, undefined>, A extends any[]>(this: E, removeCursor: (...args: A) => readonly [...Parameters<E>]): PaginationEndpoint<E, A>;
     paginated<E extends RestInstanceBase<FetchFunction, any, undefined>, C extends string>(this: E, cursorField: C): PaginationFieldEndpoint<E, C>;
-    /** Endpoint to append the next page extending a list for pagination
+    /** Concatinate the next page of results (GET)
      * @see https://dataclient.io/rest/api/RestEndpoint#getPage
      */
     getPage: 'paginationField' extends keyof O ? O['paginationField'] extends string ? PaginationFieldEndpoint<F & {
         schema: S;
         sideEffect: M;
     } & O, O['paginationField']> : undefined : undefined;
-    /** Endpoint that pushes (place at end) a newly created entity to this Collection
+    /** Create a new item (POST) and `push` to the end
      * @see https://dataclient.io/rest/api/RestEndpoint#push
      */
     push: AddEndpoint<F, ExtractCollection<S>['push'], Exclude<O, 'body' | 'method'> & {
         body: OptionsToAdderBodyArgument<O> | OptionsToAdderBodyArgument<O>[] | FormData;
     }>;
-    /** Endpoint that unshifts (place at start) a newly created entity to this Collection
+    /** Create a new item (POST) and `unshift` to the beginning
      * @see https://dataclient.io/rest/api/RestEndpoint#unshift
      */
     unshift: AddEndpoint<F, ExtractCollection<S>['unshift'], Exclude<O, 'body' | 'method'> & {
         body: OptionsToAdderBodyArgument<O> | OptionsToAdderBodyArgument<O>[] | FormData;
     }>;
-    /** Endpoint that assigns newly created entities to their respective keys in this Collection
+    /** Create new item(s) (POST) and `Object.assign` merge
      * @see https://dataclient.io/rest/api/RestEndpoint#assign
      */
     assign: AddEndpoint<F, ExtractCollection<S>, Exclude<O, 'body' | 'method'> & {
@@ -1618,15 +1618,15 @@ interface Resource<O extends ResourceGenerics = {
     path: ResourcePath;
     schema: any;
 }> extends Extendable<O> {
-    /** Get a singular item
+    /** Get one item (GET)
      *
      * @see https://dataclient.io/rest/api/createResource#get
      */
     get: GetEndpoint<{
         path: O['path'];
         schema: O['schema'];
     }>;
-    /** Get a list of item
+    /** Get an Array of items (GET)
      *
      * @see https://dataclient.io/rest/api/createResource#getlist
      */

diff --git a/website/src/components/Playground/editor-types/globals.d.ts b/website/src/components/Playground/editor-types/globals.d.ts
@@ -1267,26 +1267,26 @@ interface RestInstance<F extends FetchFunction = FetchFunction, S extends Schema
      */
     paginated<E extends RestInstanceBase<FetchFunction, any, undefined>, A extends any[]>(this: E, removeCursor: (...args: A) => readonly [...Parameters<E>]): PaginationEndpoint<E, A>;
     paginated<E extends RestInstanceBase<FetchFunction, any, undefined>, C extends string>(this: E, cursorField: C): PaginationFieldEndpoint<E, C>;
-    /** Endpoint to append the next page extending a list for pagination
+    /** Concatinate the next page of results (GET)
      * @see https://dataclient.io/rest/api/RestEndpoint#getPage
      */
     getPage: 'paginationField' extends keyof O ? O['paginationField'] extends string ? PaginationFieldEndpoint<F & {
         schema: S;
         sideEffect: M;
     } & O, O['paginationField']> : undefined : undefined;
-    /** Endpoint that pushes (place at end) a newly created entity to this Collection
+    /** Create a new item (POST) and `push` to the end
      * @see https://dataclient.io/rest/api/RestEndpoint#push
      */
     push: AddEndpoint<F, ExtractCollection<S>['push'], Exclude<O, 'body' | 'method'> & {
         body: OptionsToAdderBodyArgument<O> | OptionsToAdderBodyArgument<O>[] | FormData;
     }>;
-    /** Endpoint that unshifts (place at start) a newly created entity to this Collection
+    /** Create a new item (POST) and `unshift` to the beginning
      * @see https://dataclient.io/rest/api/RestEndpoint#unshift
      */
     unshift: AddEndpoint<F, ExtractCollection<S>['unshift'], Exclude<O, 'body' | 'method'> & {
         body: OptionsToAdderBodyArgument<O> | OptionsToAdderBodyArgument<O>[] | FormData;
     }>;
-    /** Endpoint that assigns newly created entities to their respective keys in this Collection
+    /** Create new item(s) (POST) and `Object.assign` merge
      * @see https://dataclient.io/rest/api/RestEndpoint#assign
      */
     assign: AddEndpoint<F, ExtractCollection<S>, Exclude<O, 'body' | 'method'> & {
@@ -1622,15 +1622,15 @@ interface Resource<O extends ResourceGenerics = {
     path: ResourcePath;
     schema: any;
 }> extends Extendable<O> {
-    /** Get a singular item
+    /** Get one item (GET)
      *
      * @see https://dataclient.io/rest/api/createResource#get
      */
     get: GetEndpoint<{
         path: O['path'];
         schema: O['schema'];
     }>;
-    /** Get a list of item
+    /** Get an Array of items (GET)
      *
      * @see https://dataclient.io/rest/api/createResource#getlist
      */