fix: improve doc comments and types (#169)

Also added jsdoc rules to eslint to ensure improved doc comments in
future.

Closes: #105

.eslintrc.js

@@ -1,15 +1,24 @@
 module.exports = {
   parser: '@typescript-eslint/parser',
+  ignorePatterns: [
+    'src/gen/**/*.ts',
+    'src/**/*.test.ts',
+  ],
   env: {
     node: true,
   },
+  plugins: [
+    "jsdoc",
+  ],
   extends: [
     'plugin:@typescript-eslint/eslint-recommended',
     'plugin:@typescript-eslint/recommended',
+    'plugin:jsdoc/recommended-typescript-error',
   ],
   rules: {
     '@typescript-eslint/explicit-function-return-type': 'off',
     '@typescript-eslint/ban-ts-ignore': 'off',
     '@typescript-eslint/no-explicit-any': 'off',
+    'jsdoc/tag-lines': 'off', // not documented on jsdoc plugin site, unsure how to correct.
   },
 };

package.json

@@ -50,6 +50,7 @@
     "@typescript-eslint/parser": "^4.22.0",
     "codecov": "^3.8.3",
     "eslint": "^7.24.0",
+    "eslint-plugin-jsdoc": "^40.1.0",
     "glob-run": "^0.1.7",
     "grpc-tools": "^1.11.3",
     "husky": "^6.0.0",

src/api/documents/v0/collection-group-ref.ts

@@ -41,8 +41,10 @@ export class CollectionGroupRef<T extends DocumentStructure> {
   }
 
   /**
-   * Create a CollectionGroupRef referencing a sub-collection of this collection
-   * @param name
+   * Create a CollectionGroupRef referencing a sub-collection of this collection.
+   *
+   * @param name of the sub-collection
+   * @returns a reference to the sub-collection
    */
   public collection<T extends DocumentStructure>(
     name: string
@@ -56,7 +58,8 @@ export class CollectionGroupRef<T extends DocumentStructure> {
   }
 
   /**
-   * Create a new collection query object
+   * Create a new collection query object.
+   *
    * @returns a new collection query object
    */
   public query(): Query<T> {
@@ -88,9 +91,12 @@ export class CollectionGroupRef<T extends DocumentStructure> {
   }
 
   /**
-   * Creates a collection group reference from a collection reference
-   * @param ref
-   * @param dc
+   * Creates a collection group reference from a collection reference.
+   *
+   * @internal
+   * @param ref a collection reference.
+   * @param dc a document service client.
+   * @returns a collection group reference.
    */
   public static fromCollectionRef(
     ref: CollectionRef<any>,

src/api/documents/v0/collection-ref.ts

@@ -38,10 +38,12 @@ export class CollectionRef<T extends DocumentStructure> {
   }
 
   /**
-   * Return a reference to a subcollection within the documents of this collection.
+   * Return a reference to a sub-collection within the documents of this collection.
    *
-   * Useful when querying subcollection documents across all/many parent documents. E.g. Querying landmarks from multiple cities.
-   * @param name
+   * Useful when querying sub-collection documents across all/many parent documents. E.g. Querying landmarks from multiple cities.
+   *
+   * @param name the name of the collection
+   * @returns a reference to all sub-collections matching the name provided.
    */
   public collection(name: string): CollectionGroupRef<T> {
     return CollectionGroupRef.fromCollectionRef(
@@ -52,16 +54,18 @@ export class CollectionRef<T extends DocumentStructure> {
 
   /**
    * Return a reference to a document in the collection.
-   * @param documentId id the document unique id (required)
+   *
+   * @param id the unique id of the document
    * @returns new collection document reference
    */
   public doc(id: string): DocumentRef<T> {
     return new DocumentRef<T>(this.documentClient, this, id);
   }
 
   /**
-   * Create a new collection query object
-   * @returns a new collection query object
+   * Create a new collection query object.
+   *
+   * @returns a new collection query object.
    */
   public query(): Query<T> {
     return new Query<T>(this.documentClient, this);

src/api/documents/v0/document-ref.ts

@@ -27,7 +27,7 @@ import { MAX_COLLECTION_DEPTH } from './constants';
 export type DocumentStructure = Record<string, any>;
 
 /**
- * Document Ref
+ * Document Ref.
  *
  * Provides a Document Reference class.
  * Used to create references to collections.
@@ -49,6 +49,7 @@ export class DocumentRef<T extends DocumentStructure> {
 
   /**
    * Return the collection document reference value.
+   *
    * @returns the collection document reference value, or null if not found
    */
   public async get(): Promise<T> {
@@ -78,6 +79,7 @@ export class DocumentRef<T extends DocumentStructure> {
    * Set the document content for this document reference in the database. If the
    * document does not exist an new item will be created, otherwise an
    * existing document will be update with the new value.
+   *
    * @param value content the document content to store (required)
    */
   public async set(value: T): Promise<void> {
@@ -133,6 +135,7 @@ export class DocumentRef<T extends DocumentStructure> {
 
   /**
    * Gets a Collection instance that refers to the collection at the specified path.
+   *
    * @param name The name of the collection (required)
    * @returns The Collection instance
    */

src/api/documents/v0/documents.ts

@@ -35,6 +35,7 @@ export class Documents {
 
   /**
    * Gets a Collection instance that refers to the collection at the specified path.
+   *
    * @param name The name of the collection (required)
    * @returns The Collection instance
    */
@@ -47,7 +48,8 @@ export class Documents {
 let DOCUMENTS = undefined;
 
 /**
- * Documents
+ * Documents API client.
+ *
  * @returns a Documents API client.
  * @example
  * ```typescript

src/api/documents/v0/query.test.ts

@@ -198,8 +198,7 @@ describe('Query Tests', () => {
     test('Providing an invalid paging token should throw error', async () => {
       const q = documents().collection('test').query();
 
-      //@ts-ignore
-      q.pagingFrom('test');
+      q.pagingFrom('test' as any);
 
       await expect(q.fetch()).rejects.toStrictEqual(
         new InvalidArgumentError('Invalid paging token provided!')
@@ -213,14 +212,13 @@ describe('Query Tests', () => {
       message: 'UNIMPLEMENTED',
     };
     let documentsClient: Documents;
-    let mockStream = new PassThrough();
+    const mockStream = new PassThrough();
     let queryStreamMock;
 
     beforeAll(() => {
       queryStreamMock = jest
         .spyOn(GrpcKeyDocumentsClient.prototype, 'queryStream')
-        // @ts-ignore
-        .mockReturnValueOnce(mockStream);
+        .mockReturnValueOnce(mockStream as any);
       documentsClient = documents();
     });
 
@@ -253,15 +251,14 @@ describe('Query Tests', () => {
 
   describe('Given DocumentServiceClient.QueryStream succeeds', () => {
     let documentsClient: Documents;
-    let mockStream = new PassThrough();
+    const mockStream = new PassThrough();
     let queryStreamMock;
     let mockKey;
 
     beforeAll(() => {
       queryStreamMock = jest
         .spyOn(GrpcKeyDocumentsClient.prototype, 'queryStream')
-        // @ts-ignore
-        .mockReturnValueOnce(mockStream);
+        .mockReturnValueOnce(mockStream as any);
       documentsClient = documents();
     });
 

src/api/documents/v0/query.ts

@@ -41,7 +41,8 @@ export interface FetchResponse<T> {
 }
 
 /**
- * Convenience method to convert ProtobufMap objects to standard JavaScript Maps
+ * Convenience method to convert ProtobufMap objects to standard JavaScript Maps.
+ *
  * @param protoMap map to convert
  * @returns the map
  */
@@ -122,7 +123,7 @@ export class Query<T extends DocumentStructure> {
   /**
    * Set the query paging continuation token.
    *
-   * @param pagingToken
+   * @param pagingToken used to determine where to continue paging from.
    * @returns the Query operation
    */
   public pagingFrom(pagingToken: PagingToken): Query<T> {
@@ -133,7 +134,7 @@ export class Query<T extends DocumentStructure> {
   /**
    * Set the query fetch limit.
    *
-   * @param limit
+   * @param limit the maximum number for results to return.
    * @returns the Query operation
    */
   public limit(limit: number): Query<T> {
@@ -216,6 +217,7 @@ export class Query<T extends DocumentStructure> {
 
   /**
    * Queries the collection and returns a readable stream.
+   *
    * @returns all query results as a stream
    * @example
    * ```typescript

src/api/errors/index.ts

@@ -53,8 +53,9 @@ const STATUS_CODE_MAP: Record<codes, new (message: string) => Error> = {
 };
 
 /**
- * Translates gRPC service errors to Nitric API errors
- * @param error - Original gRPC service error
+ * Translates gRPC service errors to Nitric API errors.
+ *
+ * @param error the original gRPC service error
  * @returns Nitric API error that maps to the provided service error code
  */
 export const fromGrpcError = (error: ServiceError): Error => {

src/api/events/v0/events.ts

@@ -25,6 +25,12 @@ import * as grpc from '@grpc/grpc-js';
 import type { NitricEvent } from '../../../types';
 import { fromGrpcError, InvalidArgumentError } from '../../errors';
 
+/**
+ * Construct event and topic service clients.
+ *
+ * @internal
+ * @returns event and topic service clients.
+ */
 function newEventServiceClients(): {
   event: EventServiceClient;
   topic: TopicServiceClient;
@@ -55,7 +61,8 @@ export class Topic {
   }
 
   /**
-   * Publishes an event to a nitric topic
+   * Publishes an event to a nitric topic.
+   *
    * @param event The event to publish
    * @param opts Additional publishing options
    * @returns NitricEvent containing the unique id of the event (if not provided it will be generated)
@@ -152,14 +159,13 @@ export class Eventing {
    * Get a reference to a Topic.
    *
    * @param name Name of the topic, as defined in nitric.yaml.
-   *
+   * @returns a topic resource.
    * @example
    * ```typescript
    * import { Eventing } from "@nitric/sdk";
    * const eventing = new Eventing();
    * const topic = eventing.topic('notifications');
    * ```
-   *
    */
   public topic(name: string): Topic {
     if (!name) {
@@ -172,9 +178,8 @@ export class Eventing {
   /**
    * Retrieve all available topic references by querying for available topics.
    *
-   * @retuns A promise containing the list of available nitric topics
-   *
-   * Example:
+   * @returns A promise containing the list of available nitric topics
+   * @example
    * ```typescript
    * import { Eventing } from "@nitric/sdk";
    *
@@ -202,7 +207,8 @@ export class Eventing {
 let EVENTS = undefined;
 
 /**
- * Events
+ * Events API client.
+ *
  * @returns an Events API client.
  * @example
  * ```typescript

src/api/queues/v0/queues.ts

@@ -37,7 +37,13 @@ interface FailedMessage {
   message: string;
 }
 
-/** @internal */
+/**
+ * Converts and SDK task representation to a wire representation to be sent to the Nitric Server.
+ *
+ * @internal
+ * @param task to convert
+ * @returns the wire representation of the task
+ */
 function taskToWire(task: Task) {
   const wireTask = new NitricTask();
 
@@ -48,6 +54,11 @@ function taskToWire(task: Task) {
   return wireTask;
 }
 
+/**
+ * Constructs a new queue service client.
+ *
+ * @returns a queue service client.
+ */
 function newQueueServiceClient(): QueueServiceClient {
   return new QueueServiceClient(
     SERVICE_BIND,
@@ -269,7 +280,8 @@ export class ReceivedTask implements Task {
 let QUEUES = undefined;
 
 /**
- * Queues
+ * Queues API Client.
+ *
  * @returns a Queues API client.
  * @example
  * ```typescript