Class specific callbacks

[mramato]

JSDoc defines class-specific callbacks as part of the standard callback convention: https://jsdoc.app/tags-callback.html

They do not appear to work in tsd-jsdoc because it just passes through the ~ character as part of the TS declaration name. As these are meta types, it shouldn't be too hard to support them.

A naive approach would just be to remove ~ from any identifier when it is encountered during processing, which should work in 99% of the cases.

Another, possible more complete, approach is to change ~ to . and write out the callback function definition as a member of the class the class-specific callback is on.

Is there any reason this would be difficult to add to tsd-jsdoc? I'm happy to submit a pull request with the code and relevant tests if you could point me in the right area of the code to get started.

Thanks!

[mramato]

Actually, looking at this with fresh eyes, it appears that class specific callbacks are supported! It's only the~ notation that is not handled. I'm going to try switching my code base completely from ~ notation to . and see what happens.

[mramato]

Switch to dot notation worked, and is an acceptable answer for my case (though working with ~ would be nice). So I'm closing this. Thanks for an awesome tool!

[glen-84]

@mramato,

I'm affected by this as well, would you consider reopening this issue, or should I create a new one?

[mramato]

@glen-84 Is modifying your callbacks to use . instead of ~ an option?

Technically this is a bug either way, so I suppose I'll re-open it, but I don't know if it will be addressed anytime soon. I would still like to dig into the code a little and see if it's an easy fix.

[glen-84]

@glen-84 Is modifying your callbacks to use . instead of ~ an option?

I was trying to add type definitions to a project that I'm not the owner of (xlsx-populate). In theory I could probably change the syntax used or do a regex-replace on the generated definitions, but since this is supported JSDoc syntax, it would be better if it was supported without having to make any changes.

However, I've just run into another issue with modules/exports, so IDK if I'll be able to use this library.

[englercj]

PRs welcome.

[thw0rted]

As a JSDoc yellow-belt, I don't really understand. Is there a difference in meaning between . vs ~, such that one is "correct" here and the other isn't? Or are they really synonymous?

[glen-84]

As a JSDoc yellow-belt, I don't really understand. Is there a difference in meaning between . vs ~, such that one is "correct" here and the other isn't? Or are they really synonymous?

According to this:

• # is used for instance members.
• . is used for static members.
• ~ is used for inner members.

[thw0rted]

Sounds like "namepath" is the magic word I was missing. Thanks!

Does this mean that Matt's original documentation was technically using it wrong? I think he was documenting the public API, so not actually talking about "inner members" (sorta-kinda analogous to class private functions, but not really).

For that matter, when is "inner member" syntax actually useful at all? The docs you linked say a namepath is for "referring to a JavaScript variable that is elsewhere in your documentation" -- if I'm documenting File A, why would I need to talk about some inner members in File B if there's no way for me to actually address them at runtime? That's the whole point of hiding the inner inside an inaccessible scope, right?

[glen-84]

Does this mean that Matt's original documentation was technically using it wrong?

He was documenting class-specific callbacks, as far as I know, which do use the tilde syntax.

For that matter, when is "inner member" syntax actually useful at all?

That is answered on the same page:

You might wonder why there is a syntax to refer to an inner method when that method isn't directly accessible from outside the function it is defined in. While that is true, and thus the "~" syntax is rarely used, it is possible to return a reference to an inner method from another method inside that container, so it is possible that some object elsewhere in your code might borrow an inner method.

[thw0rted]

That seems like an oversight in the JSDoc docs. On the @callback page they use ~ as the namepath connector, but on the "About Namepaths" page they do not mention callbacks at all. You could argue that a callback is somehow an "inner member" of a class but really it's just an "idea" associated with the class, closest to an @interface. Of course, those also use tilde-namepaths in the example, and they're also conspicuously absent on the namepath page, so 🤷