You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Just as you support @property for the @typedef declaration, please also support @property for @class/@constructs (etc.) declarations. My preference would be that it should work exactly as the @typedef one does, only applied to actual code objects rather than phantom ones.
Use Cases
When using Object.defineProperties to define properties that, for example, follow a dynamic naming convention and are not explicitly named.
When creating Proxy objects that trap the getPrototypeOf value and therefore have a type assigned.
Examples
The use case that prompted this request is a pure-JS factory file that creates a Proxy instance. (I have simplified this example a lot; I am actually using a factory pattern rather than the constructor, but this is easier to read and still works.) The problem is, to document what properties are available via the proxy, I cannot currently do this obvious syntax, which is valid JSDoc syntax:
/** @class MyClass
* @property email {string} The user's email
* @property name {string} The user's name
*/
class MyClass {
constructor( target ) {
return new Proxy( target, proxyHandler );
}
}
const proxyHandler = {
// lots of stuff here
getPrototypeOf: () => MyClass.prototype // this is how it will later be instanceof MyClass
}
// ... later in another file ...
import MyClass from './MyClass.js';
/** @param {MyClass|OtherClass} the data
*/
getUserEmail( myInstance ) {
if ( myInstance instanceof MyClass ) {
return myInstance.email;
}
}
As you can see in the example function, I could certainly use @typedef to declare MyClass in order to get the @param {MyClass} part to work, but I could not also use instanceof with the same symbol.
The way I got it working for TypeScript was like this, which is annoyingly verbose. In my actual case, it takes more than 100 lines of code just to declare all the properties.
/** @class MyClass
*/
class MyClass {
constructor( target ) {
/** The user's email.
* @type {string}
*/
this.email = undefined;
/** The user's name.
* @type {string}
*/
this.name = undefined;
return new Proxy( target, proxyHandler );
}
}
const proxyHandler = {
// lots of stuff here
getPrototypeOf: () => MyClass.prototype // this is how it will later be instanceof MyClass
}
Checklist
My suggestion meets these guidelines:
[ x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
[ x] This wouldn't change the runtime behavior of existing JavaScript code
[ x] This could be implemented without emitting different JS based on the types of the expressions
[ x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
Uh oh!
There was an error while loading. Please reload this page.
Search Terms JSDoc @Property
Suggestion
Just as you support
@property
for the@typedef
declaration, please also support@property
for@class/@constructs
(etc.) declarations. My preference would be that it should work exactly as the@typedef
one does, only applied to actual code objects rather than phantom ones.Use Cases
Object.defineProperties
to define properties that, for example, follow a dynamic naming convention and are not explicitly named.getPrototypeOf
value and therefore have a type assigned.Examples
The use case that prompted this request is a pure-JS factory file that creates a Proxy instance. (I have simplified this example a lot; I am actually using a factory pattern rather than the constructor, but this is easier to read and still works.) The problem is, to document what properties are available via the proxy, I cannot currently do this obvious syntax, which is valid JSDoc syntax:
As you can see in the example function, I could certainly use
@typedef
to declareMyClass
in order to get the@param {MyClass}
part to work, but I could not also useinstanceof
with the same symbol.The way I got it working for TypeScript was like this, which is annoyingly verbose. In my actual case, it takes more than 100 lines of code just to declare all the properties.
Checklist
My suggestion meets these guidelines:
The text was updated successfully, but these errors were encountered: