@template {Ctor} [C = Ctor<typeof Complex>] #2384
Description
Search terms
Expected Behavior
Create doc.
Actual Behavior
Fails to create doc.
Steps to reproduce the bug
Environment
- Typedoc version: 0.25.0
- TypeScript version: 5.2.2
- Node.js version: 9.8.1
- OS: Windows 8.1
Minimal MJS code:
// @ts-check
/**
* @typedef {Int8Array | Uint8Array | Uint8ClampedArray | Int16Array |
* Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array |
* BigInt64Array | BigUint64Array} TypedArray
* A union type representing all possible TypedArrays.
*/
/**
* @template {Typed} [T = Typed<TypedArray>]
* @typedef {T} Typed A generic type representing a TypedArray.
*/
/**
* @template {Ctor} [C = Ctor<typeof Complex>]
* @typedef {C} Ctor A generic type representing a `Complex` constructor.
*/
/**
* @template {Ctor} C
* @typedef {InstanceType<C>} Cinst
* A generic type representing an instance of a constructor `C`.
*/
/**
* @template {Ctor} C
* @typedef {Ctor<C> | {} | void} Cvoid
* A union type representing either a constructor `C`, an object, or void.
* Used to hint that a static method can also be invoked "bare".
*/
/**
* @template T
* @typedef {new (...args: any) => T} Newable
* A constructor type that can be instantiated with the `new` keyword.
*/
/**
* An immutable complex number with real and imaginary parts.
* @class Complex
*/
export default class Complex {
/**
* Create a new instance of the Complex class.
* @constructor
* @param {number} [re=0] - The real part of the complex number.
* @param {number} [im=0] - The imaginary part of the complex number.
*/
constructor(re = 0, im = 0) {
/**
* The real part of the complex number.
* @readonly
* @const
* @type {number}
*/
this.real = +re || 0;
/**
* The imaginary part of the complex number.
* @readonly
* @const
* @type {number}
*/
this.imag = +im || 0;
}
/**
* Static property's name to check if some constructor is of type Complex.
* @protected
* @static
* @readonly
* @const {'fromRI'}
*/
static _METHOD = 'fromRI';
/**
* Check if a function is a Complex datatype constructor.
* @protected
* @static
* @template {Ctor} C - Extends typeof Complex.
* @param {Cvoid<C>} c - The constructor function to check.
* @return {c is Newable<Cinst<C>>}
* True if param c is or inherits from Complex class.
*/
static _isComplex(c) {
return !!c && Complex._METHOD in c;
}
/**
* Get input constructor c if typeof Complex; or fallback to Complex.
* @protected
* @static
* @template {Ctor} C - Extends typeof Complex.
* @template {Newable<Cinst<C>>} N - Constructor for typeof Complex.
* @param {Cvoid<C>} c - The constructor function to verify.
* @return {N} Param c if type Complex; otherwise a Complex constructor.
*/
static _ctor(c) {
return /** @type {N} */ (Complex._isComplex(c) ? c : this || Complex);
}
/**
* Create a new instance of a given Complex constructor function.
* @protected
* @static
* @template {Ctor} C - Extends typeof Complex.
* @param {Cvoid<C>} c - An existing Complex constructor.
* @param {*} args - Real & imaginary number parts.
* @return {Cinst<C>} A new instance of a complex number.
*/
static _new(c, ...args) {
return new (this._ctor(c))(...args);
}
}TypeDoc doesn't like these 2 @template tags:
/**
* @template {Typed} [T = Typed<TypedArray>]
* @typedef {T} Typed A generic type representing a TypedArray.
*/
/**
* @template {Ctor} [C = Ctor<typeof Complex>]
* @typedef {C} Ctor A generic type representing a `Complex` constructor.
*/It fails to complete the task w/ these 2 errors:
[error] Failed to find JSDoc tag for T after parsing comment, please file a bug report.
- @template {Typed} [T = Typed]
[error] Failed to find JSDoc tag for C after parsing comment, please file a bug report.
- @template {Ctor} [C = Ctor]
As a workaround, I could move those 2 inside the class itself.
Doing so, TypeDoc fully runs and outputs the doc.
However, it'll simply ignore the existence of both @template tags!
It then displays this extra warning btw:
[warning] Ctor, defined in ./complex.mjs, is referenced by Cvoid but not included in the documentation.
I wonder if there's some other alternative syntax to constrain a type to Complex type and any possible subclass of it...