[IDEA] Add JSDoc to AST

[linonetwo]

Is your feature request related to a problem? Please describe.

To build WYSIWYG editor, I need to maintain https://github.com/tiddly-gittly/wikiast , but it's dev experience is so bad that I don't want to touch it for a while.

Describe the solution you'd like

At least move AST part of typing from https://github.com/tiddly-gittly/TW5-Typed to the tw core, using JSDoc like how svelte does ( https://news.ycombinator.com/item?id=35932617 )

Example:

https://github.com/sveltejs/svelte/blob/1681b218cf3b42757f7d0f0a7c0dc45a79fea6f0/packages/svelte/src/store/shared/index.js#L7-L10

Describe alternatives you've considered

Directly use .d.ts may be better, but inline typing will make sure people update it.

Currently AST type in TW5-Typed is broken, the wikiast's code is in a mess. My time on opensource is liminted, so I need auto type checker to help GPT4 to help me. (GPT works better with type check output)

Additional context

I've heard that tw core maintainers don't like TS even JSDoc, but the fact is plugin developer need it, I need it, so please consider providing a better experience here. (Obsidian provides TS SDK and plugin template even it is close-sourced. Many people misunderstood Obsidian is opensourced because of its opensource plugin community. Consider how it attract modern web developers to contribute so much plugins)

[pmario]

I think the right article to link to - is: https://www.puruvj.dev/blog/get-to-know-typescript--using-typescript-without-typescript

It has been mentioned in: https://devclass.com/2023/05/11/typescript-is-not-worth-it-for-developing-libraries-says-svelte-author-as-team-switches-to-javascript-and-jsdoc/

I personally would love to get "autocomplete" and "type popups" if I hover a TW function in VSCode. IMO JSDOC is not too much different, to what we do have already. We will probably increase the source code size a bit, but I think the wins would be worth it.

What we have atm is suboptimal. eg: Just yesterday I had to lookup the GitHub-saver code for a thread at Talk

1. There are several function calls to this.wiki.* and $tw.utils.*
2. If we want to see how they work and if there are optional paramters we have to do a global search
   1. eg: $tw.utils.getPassword -- To have a chance to find the function definition we need to search for .getPassword
   2. In this case we are lucky, because there are only 10 matches in 7 files but for other search-terms there may be 100++ matches
   3. The pain point is, that VSCode searches the whole structure, so I constantly need to maintain "include" extension
   4. 
3. I need to open the file to see which "type" the "name" parameter is.
   1. 
   2. There is some documentation 3 lines, but no type in formation
4. The info for window.localStorage.getItem() is much nicer
   1. 
5. A bit of JSDoc woul look like this
   1. 
   2. and the popup would be like this
   3. 

That's nice, but how can we tell VSCode, where to find that info in $:/core/modules/savers/github.js

If we could improve the inline documentation in a way, that VSCode Intellisense automatically recognises it, in the whole project, I would support the effort.

VSCode does understand JSDoc -- and JSDoc understands commonjs - require(module-name) -- but JSDoc does not understand where to find the TW module: $:/core/modules/utils/dom.js in the project directory structure.

Because TW implements its own require function

So IMO $tw.modules.execute(moduleName,moduleRoot)
is responsible to actually find the relation between TW title: $:/core/modules/utils/dom.js and where to find it on disk.

We would need to let JSDoc know, how to use this info.

There is a second relation -- eg: $tw.utils.getPassword() actually comes from $:/core/modules/utils/dom.js because it is "merged" into the global namespace $tw.utils.* because it has modul-type: utils. -> Every exported function with that type is available as $tw.utils.*

JSDoc also has no idea about that relation, but it would need to know it to give proper info if you hover $tw.utils.getPassword

Just some thoughts.

@Jermolene -- Did you ever have a closer look at JSDoc in relation with TW source code?

[linonetwo]

@pmario

JSDoc does not understand where to find the TW module: $:/core/modules/utils/dom.js in the project directory structure.

Maybe sourcemap can handle this, no JSDoc/TS required.

Or use .d.ts file like https://github.com/tiddly-gittly/TW5-Typed/blob/master/src/modules/utils/parsetree.d.ts#L5

https://github.com/tiddly-gittly/TW5-Typed/blob/master/src/modules/utils/index.d.ts

https://github.com/tiddly-gittly/TW5-Typed/blob/master/src/core.d.ts#L164

I personally would love to get "autocomplete" and "type popups" if I hover a TW function in VSCode

And this will only require JSDoc, no sourcemap/TS reuqired.

Currently I only care about AST node, they change frequent than other methods. Other methods in https://github.com/tiddly-gittly/TW5-Typed haven't break since they are added.

I can add PR to add some type, but #8255 may cause conflict and rework. An example here #8533

[Jermolene]

I've heard that tw core maintainers don't like TS even JSDoc, but the fact is plugin developer need it, I need it, so please consider providing a better experience here

My views are:

• I am not personally enthusiastic for TypeScript for reasons too tedious and arcane to get into here, but I do recognise that others enjoy it, and I would absolutely like for TiddlyWiki to offer a great dev experience for people who choose to write plugins in TS
• I would very much like for TW to adopt JSDoc. Further, I'd like to include a JS parser in the core that understands JSDoc comments and formats them nicely

[CodaCodr]

• I am not personally enthusiastic for TypeScript for reasons too tedious and arcane to get into here

I'm with you. For those unaware of the negatives (sorry, there are many), and are unwilling to spend the hours necessary to do the full-on, deepdive analyses, grab a coffee (or six) and head here:

https://medium.com/javascript-scene/the-typescript-tax-132ff4cb175b

https://medium.com/javascript-scene/the-shocking-secret-about-static-types-514d39bf30a3

https://medium.com/javascript-scene/you-might-not-need-typescript-or-static-types-aa7cb670a77b