Type annotations should try use JSDoc

[Akxe]

What are you trying to achieve?

If CodeceptJS really want to play nice with TypeScript, than they should try at least try to parse JSDoc, best would be if the files would not by analysed by other tool that the one that will help developers write it. Therefor I would suggest using TS compiler to get hints about types of functions as well as their return types. Also this would give us ability to comment our code (for library, but for users too).

Take this, it is very well annotated, but I can't enable type checking (//@ts-check) due to Helper not being in definitions. (fixed in #1206)

class NetworkHelper extends Helper {

	/**
	 * Gets first request log that passes matcher function.
	 * @param {{ url: string }} key
	 * @param {(log: IrequestLog) => boolean} matcher
	 * @return {IrequestLog}
	 */
	grabRequestLogThatMatches(key, matcher) {
		return this.grabRequestLog(key).instances.find(matcher);
	}

	/**
	 * Tests request log that passes matcher function exists.
	 * @param {{ url: string }} key
	 * @param {(log: IrequestLog) => boolean} matcher
	 * @param {string} matcherDescription Is used to described what matcher does, if test fails.
	 */
	seeRequestLogMatches(key, matcher, matcherDescription) {
		if (!this.grabRequestLogThatMatches(key, matcher)) {
			throw new Error(`No request logs matches: ${matcherDescription}`);
		}
	}
}

/**
 * Storage of requests.
 * - Using `WeakMap` levreges the need to clean up after test, as the reference to the key are lost.
 * @type {WeakMap<{ url: string }, IrequestLog>}
 */
NetworkHelper.requestMap = new WeakMap();

/** @typedef {{ readonly count: number, instances: { url: string, method: import("puppeteer").HttpMethod, headers: import("puppeteer").Headers, postData: string, response: import("puppeteer").Response }[] }} IrequestLog */

I would expect the steps.d.ts to look like this:

type IrequestLog = {{ readonly count: number, instances: { url: string, method: import("puppeteer").HttpMethod, headers: import("puppeteer").Headers, postData: string, response: import("puppeteer").Response }[] }};

declare namespace CodeceptJS {
  export interface I {
    //other definitions...
	/**
	 * Gets first request log that passes matcher function.
	 */
    grabRequestLogThatMatches(key: { url: string }, matcher: (log: IrequestLog) => boolean) : IrequestLog,
	/**
	 * Tests request log that passes matcher function exists.
	 * @param matcherDescription Is used to described what matcher does, if test fails.
	 */
    seeRequestLogMatchess(key: { url: string }, matcher: (log: IrequestLog) => boolean, matcherDescription: string) : void,
  }
}

What do you get instead?

declare namespace CodeceptJS {
  export interface I {
    //other definitions...
    grabRequestLogThatMatches(key: string, matcher: string) : Promise<string>,
    seeRequestLogMatchess(key: string, matcher: string, matcherDescription: string) : void,
  }
}

This is completely different! Unusable I can't do anything with this... IDE will cry and I can either disable it or comment every user made type annotation...

If at leas you have put type any, it would be inconvenient, but this is unusable.

Details

• CodeceptJS version: 1.3.3
• NodeJS Version: 9.11.1
• Operating System: Windows