Migrate from JSDoc to TypeDoc (#3375)

Author: Cole-Greer

gremlin-js/gremlin-javascript/lib/driver/client.ts

@@ -33,7 +33,7 @@ export type RequestOptions = {
   params?: Record<string, any>;
 };
 
-type ClientOptions = ConnectionOptions & RequestOptions & { processor?: string };
+export type ClientOptions = ConnectionOptions & RequestOptions & { processor?: string };
 
 /**
  * A {@link Client} contains methods to send messages to a Gremlin Server.
@@ -44,22 +44,7 @@ export default class Client {
   /**
    * Creates a new instance of {@link Client}.
    * @param {String} url The resource uri.
-   * @param {Object} [options] The connection options.
-   * @param {Array} [options.ca] Trusted certificates.
-   * @param {String|Array|Buffer} [options.cert] The certificate key.
-   * @param {String|Buffer} [options.pfx] The private key, certificate, and CA certs.
-   * @param {GraphBinaryReader} [options.reader] The reader to use.
-   * @param {Boolean} [options.rejectUnauthorized] Determines whether to verify or not the server certificate.
-   * @param {String} [options.traversalSource] The traversal source. Defaults to: 'g'.
-   * @param {GraphBinaryWriter} [options.writer] The writer to use.
-   * @param {Authenticator} [options.authenticator] The authentication handler to use.
-   * @param {Object} [options.headers] An associative array containing the additional header key/values for the initial request.
-   * @param {Boolean} [options.enableUserAgentOnConnect] Determines if a user agent will be sent during connection handshake. Defaults to: true
-   * @param {String} [options.processor] The name of the opProcessor to use, leave it undefined or set 'session' when session mode.
-   * @param {String} [options.session] The sessionId of Client in session mode. Defaults to null means session-less Client.
-   * @param {http.Agent} [options.agent] The http.Agent implementation to use.
-   * @param {RequestInterceptor|RequestInterceptor[]} [options.interceptors] One or more request interceptors to apply before each HTTP request.
-   * @constructor
+   * @param {ClientOptions} [options] The connection options.
    */
   constructor(
     url: string,

gremlin-js/gremlin-javascript/lib/driver/connection.ts

@@ -81,19 +81,7 @@ export default class Connection extends EventEmitter {
   /**
    * Creates a new instance of {@link Connection}.
    * @param {String} url The resource uri.
-   * @param {Object} [options] The connection options.
-   * @param {Array} [options.ca] Trusted certificates.
-   * @param {String|Array|Buffer} [options.cert] The certificate key.
-   * @param {String|Buffer} [options.pfx] The private key, certificate, and CA certs.
-   * @param {GraphBinaryReader} [options.reader] The reader to use.
-   * @param {Boolean} [options.rejectUnauthorized] Determines whether to verify or not the server certificate.
-   * @param {String} [options.traversalSource] The traversal source. Defaults to: 'g'.
-   * @param {GraphBinaryWriter} [options.writer] The writer to use. Set to null to skip serialization.
-   * @param {Object} [options.headers] An associative array containing the additional header key/values for the initial request.
-   * @param {Boolean} [options.enableUserAgentOnConnect] Determines if a user agent will be sent during connection handshake. Defaults to: true
-   * @param {http.Agent} [options.agent] The http.Agent implementation to use.
-   * @param {RequestInterceptor|RequestInterceptor[]} [options.interceptors] One or more request interceptors to apply before each HTTP request.
-   * @constructor
+   * @param {ConnectionOptions} [options] The connection options.
    */
   constructor(
     readonly url: string,

gremlin-js/gremlin-javascript/lib/driver/driver-remote-connection.ts

@@ -30,7 +30,7 @@ import GremlinLang from '../process/gremlin-lang.js';
 import { ConnectionOptions } from './connection.js';
 
 /**
- * Represents the default {@link RemoteConnection} implementation.
+ * Represents the default `RemoteConnection` implementation.
  */
 export default class DriverRemoteConnection extends RemoteConnection {
   private readonly _client: Client;
@@ -39,19 +39,6 @@ export default class DriverRemoteConnection extends RemoteConnection {
    * Creates a new instance of {@link DriverRemoteConnection}.
    * @param {String} url The resource uri.
    * @param {ConnectionOptions} [options] The connection options.
-   * @param {Array} [options.ca] Trusted certificates.
-   * @param {String|Array|Buffer} [options.cert] The certificate key.
-   * @param {String|Buffer} [options.pfx] The private key, certificate, and CA certs.
-   * @param {GraphBinaryReader} [options.reader] The reader to use.
-   * @param {Boolean} [options.rejectUnauthorized] Determines whether to verify or not the server certificate.
-   * @param {String} [options.traversalSource] The traversal source. Defaults to: 'g'.
-   * @param {GraphBinaryWriter} [options.writer] The writer to use.
-   * @param {Authenticator} [options.authenticator] The authentication handler to use.
-   * @param {Object} [options.headers] An associative array containing the additional header key/values for the initial request.
-   * @param {Boolean} [options.enableUserAgentOnConnect] Determines if a user agent will be sent during connection handshake. Defaults to: true
-   * @param {http.Agent} [options.agent] The http.Agent implementation to use.
-   * @param {RequestInterceptor|RequestInterceptor[]} [options.interceptors] One or more request interceptors to apply before each HTTP request.
-   * @constructor
    */
   constructor(url: string, options: ConnectionOptions = {}) {
     super(url, options);

gremlin-js/gremlin-javascript/lib/process/anonymous-traversal.ts

@@ -30,20 +30,20 @@ import GremlinLang from './gremlin-lang.js';
  */
 export default class AnonymousTraversalSource {
   /**
-   * Creates a new instance of {@code AnonymousTraversalSource}.
-   * @param {Function} [traversalSourceClass] Optional {@code GraphTraversalSource} constructor.
-   * @param {Function} [traversalClass] Optional {@code GraphTraversal} constructor.
+   * Creates a new instance of `AnonymousTraversalSource`.
+   * @param {Function} [traversalSourceClass] Optional `GraphTraversalSource` constructor.
+   * @param {Function} [traversalClass] Optional `GraphTraversal` constructor.
    */
   constructor(
     readonly traversalSourceClass?: typeof GraphTraversalSource,
     readonly traversalClass?: typeof GraphTraversal,
   ) {}
 
   /**
-   * Constructs an {@code AnonymousTraversalSource} which will then be configured to spawn a
+   * Constructs an `AnonymousTraversalSource` which will then be configured to spawn a
    * {@link GraphTraversalSource}.
-   * @param {Function} [traversalSourceClass] Optional {@code GraphTraversalSource} constructor.
-   * @param {Function} [traversalClass] Optional {@code GraphTraversalSource} constructor.
+   * @param {Function} [traversalSourceClass] Optional `GraphTraversalSource` constructor.
+   * @param {Function} [traversalClass] Optional `GraphTraversalSource` constructor.
    * @returns {AnonymousTraversalSource}.
    */
   static traversal(traversalSourceClass?: typeof GraphTraversalSource, traversalClass?: typeof GraphTraversal) {

gremlin-js/gremlin-javascript/lib/process/graph-traversal.ts

@@ -113,7 +113,7 @@ export class GraphTraversalSource {
   /**
    * Graph Traversal Source with method.
    * @param {String} key
-   * @param {Object} value if not specified, the value with default to {@code true}
+   * @param {Object} value if not specified, the value with default to `true`
    * @returns {GraphTraversalSource}
    */
   with_(key: string, value: object | undefined = undefined): GraphTraversalSource {

gremlin-js/gremlin-javascript/lib/process/traversal-strategy.ts

@@ -30,7 +30,6 @@ export class TraversalStrategies {
   /**
    * Creates a new instance of TraversalStrategies.
    * @param {TraversalStrategies} [parent] The parent strategies from where to clone the values from.
-   * @constructor
    */
   constructor(parent?: TraversalStrategies) {
     if (parent) {
@@ -106,7 +105,7 @@ export class ElementIdStrategy extends TraversalStrategy {
 
 export class HaltedTraverserStrategy extends TraversalStrategy {
   /**
-   * @param {String} haltedTraverserFactory full qualified class name in Java of a {@code HaltedTraverserFactory} implementation
+   * @param {String} haltedTraverserFactory full qualified class name in Java of a `HaltedTraverserFactory` implementation
    */
   constructor({haltedTraverserFactory = ""}) {
     super({haltedTraverserFactory: haltedTraverserFactory});
@@ -127,14 +126,19 @@ export class OptionsStrategy extends TraversalStrategy {
 
 export class PartitionStrategy extends TraversalStrategy {
   /**
-   * @param {Object} [options]
-   * @param {String} [options.partitionKey] name of the property key to partition by
-   * @param {String} [options.writePartition] the value of the currently write partition
-   * @param {Array<String>} [options.readPartitions] list of strings representing the partitions to include for reads
-   * @param {boolean} [options.includeMetaProperties] determines if meta-properties should be included in partitioning defaulting to false
+   * @param options
+   * @param options.partitionKey - name of the property key to partition by
+   * @param options.writePartition - the value of the currently write partition
+   * @param options.readPartitions - list of strings representing the partitions to include for reads
+   * @param options.includeMetaProperties - determines if meta-properties should be included in partitioning defaulting to false
    */
-  constructor(options: TraversalStrategyConfiguration) {
-    super(options);
+  constructor({partitionKey, writePartition, readPartitions, includeMetaProperties}: {partitionKey?: string, writePartition?: string, readPartitions?: string[], includeMetaProperties?: boolean} = {}) {
+    const config: Record<string, any> = {};
+    if (partitionKey !== undefined) config.partitionKey = partitionKey;
+    if (writePartition !== undefined) config.writePartition = writePartition;
+    if (readPartitions !== undefined) config.readPartitions = readPartitions;
+    if (includeMetaProperties !== undefined) config.includeMetaProperties = includeMetaProperties;
+    super(config);
   }
 }
 
@@ -146,33 +150,29 @@ export class ProfileStrategy extends TraversalStrategy {
 
 export class SubgraphStrategy extends TraversalStrategy {
   /**
-   * @param {Object} [options]
-   * @param {GraphTraversal} [options.vertices] name of the property key to partition by
-   * @param {GraphTraversal} [options.edges] the value of the currently write partition
-   * @param {GraphTraversal} [options.vertexProperties] list of strings representing the partitions to include for reads
-   * @param {boolean} [options.checkAdjacentVertices] enables the strategy to apply the {@code vertices} filter to the adjacent vertices of an edge.
+   * @param options
+   * @param options.vertices - traversal to filter vertices
+   * @param options.edges - traversal to filter edges
+   * @param options.vertexProperties - traversal to filter vertex properties
+   * @param options.checkAdjacentVertices - enables the strategy to apply the `vertices` filter to the adjacent vertices of an edge.
    */
-  constructor(options: TraversalStrategyConfiguration) {
-    super(options);
-    if (this.configuration.vertices instanceof Traversal) {
-      this.configuration.vertices = this.configuration.vertices.gremlinLang;
-    }
-    if (this.configuration.edges instanceof Traversal) {
-      this.configuration.edges = this.configuration.edges.gremlinLang;
-    }
-    if (this.configuration.vertexProperties instanceof Traversal) {
-      this.configuration.vertexProperties = this.configuration.vertexProperties.gremlinLang;
-    }
+  constructor({vertices, edges, vertexProperties, checkAdjacentVertices}: {vertices?: any, edges?: any, vertexProperties?: any, checkAdjacentVertices?: boolean} = {}) {
+    const config: Record<string, any> = {};
+    if (vertices !== undefined) config.vertices = vertices instanceof Traversal ? vertices.gremlinLang : vertices;
+    if (edges !== undefined) config.edges = edges instanceof Traversal ? edges.gremlinLang : edges;
+    if (vertexProperties !== undefined) config.vertexProperties = vertexProperties instanceof Traversal ? vertexProperties.gremlinLang : vertexProperties;
+    if (checkAdjacentVertices !== undefined) config.checkAdjacentVertices = checkAdjacentVertices;
+    super(config);
   }
 }
 
 export class ProductiveByStrategy extends TraversalStrategy {
   /**
-   * @param {Object} [options]
-   * @param {Array<String>} [options.productiveKeys] set of keys that will always be productive
+   * @param options
+   * @param options.productiveKeys - set of keys that will always be productive
    */
-  constructor(options: TraversalStrategyConfiguration) {
-    super(options);
+  constructor({productiveKeys = []} = {}) {
+    super({productiveKeys});
   }
 }
 
@@ -313,8 +313,9 @@ export class ReadOnlyStrategy extends TraversalStrategy {
 
 export class EdgeLabelVerificationStrategy extends TraversalStrategy {
   /**
-   * @param {boolean} logWarnings determines if warnings should be written to the logger when verification fails
-   * @param {boolean} throwException determines if exceptions should be thrown when verifications fails
+   * @param options
+   * @param options.logWarnings - determines if warnings should be written to the logger when verification fails
+   * @param options.throwException - determines if exceptions should be thrown when verifications fails
    */
   constructor({logWarnings = false, throwException = false} = {}) {
     super({
@@ -326,9 +327,10 @@ export class EdgeLabelVerificationStrategy extends TraversalStrategy {
 
 export class ReservedKeysVerificationStrategy extends TraversalStrategy {
   /**
-   * @param {boolean} logWarnings determines if warnings should be written to the logger when verification fails
-   * @param {boolean} throwException determines if exceptions should be thrown when verifications fails
-   * @param {Array<String>} keys the list of reserved keys to verify
+   * @param options
+   * @param options.logWarnings - determines if warnings should be written to the logger when verification fails
+   * @param options.throwException - determines if exceptions should be thrown when verifications fails
+   * @param options.keys - the list of reserved keys to verify
    */
   constructor({ logWarnings = false, throwException = false, keys = ['id', 'label'] } = {}) {
     super({

gremlin-js/gremlin-javascript/lib/process/traversal.ts

@@ -255,7 +255,6 @@ class PeerPressure {
 export class P<T1 = any, T2 = any> {
   /**
    * Represents an operation.
-   * @constructor
    */
   constructor(
     public operator: string,
@@ -379,7 +378,6 @@ function createP(operator: string, args: any) {
 export class TextP<T1 = any, T2 = any> {
   /**
    * Represents an operation.
-   * @constructor
    */
   constructor(
     public operator: string,

gremlin-js/gremlin-javascript/package.json

@@ -67,11 +67,11 @@
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.0.0",
     "globals": "^15.14.0",
-    "jsdoc": "^4.0.5",
     "js-yaml": "^3.14.2",
     "mocha": "^11.7.5",
     "prettier": "^3.0.0",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.28.18",
     "typescript": "^5.4.2"
   },
   "repository": {
@@ -98,7 +98,7 @@
     "features-docker": "npm run features-graphbinary-docker",
     "features-graphbinary-docker": "cross-env NODE_OPTIONS='--loader ts-node/esm' TS_NODE_PROJECT='tsconfig.test.json' CLIENT_MIMETYPE='application/vnd.graphbinary-v4.0' cucumber-js --tags \"not @DataBigDecimal and not @DataBigInt and not @DataUUID and not @DataLong and not @StepWrite\" --import test/cucumber ../gremlin-test/",
     "lint": "eslint --ext .js .",
-    "doc": "jsdoc -r -d doc -R README.md lib/"
+    "doc": "typedoc --out doc --readme README.md --entryPointStrategy expand --entryPoints 'lib/**/*.ts' --tsconfig tsconfig.json --exclude 'lib/language/grammar/**'"
   },
   "engines": {
     "node": ">=22"