JSDoc Comments for Intellisense Help

Scripting and setups with Visual Studio Code (vscode) and AutoHotkey.
User avatar
FanaticGuru
Posts: 1907
Joined: 30 Sep 2013, 22:25

JSDoc Comments for Intellisense Help

Post by FanaticGuru » 28 Nov 2023, 14:48

I just discovered that you can use comments to create Intellisense prompts on mouseover and autocomplete.

Code: Select all

/**
 * @Class {Object} 				Manage Paints
 * @property {String} Color		Any Color Under the Sun
 * @property {String} BaseType 	Oil, Water, Latex, etc.
 */
Class Paint
{
	/** @property {String} Color	Any Color Under the Sun */
	Color
	{
		set => this.myColor := Value
		get => this.myColor
	}
	BaseType
	{
		set => this.myBaseType := Value
		get => this.myBaseType
	}
}

X := Paint()
X.Color := 'Red'
X.BaseType := 'Oil'
Mousing over Paint gets you a nice help. And mousing over Color gets a nice help.

But mousing over BaseType does not.

Do you have to put the JSDoc comment directly before each item or is there a way to have the JSDoc comment at the top provide all the Intellisense information needed for individual item help?

I am assuming that the JSDoc comments have to be intersperse throughout the entire class/function which is a little burdensome but I am not sure. It would be nice if I could create all the Intellisense information in one block at the top of the class.

Any help or suggestions on creating Intellisense help through JSDoc comments would be appreciated. It was not easy to find useful information on the subject. Apparently in other languages there are tools that automatically create all the JSDoc comments for you throughout the code but did not see anything like that for AutoHotkey.

FG
Hotkey Help - Help Dialog for Currently Running AHK Scripts
AHK Startup - Consolidate Multiply AHK Scripts with one Tray Icon
Hotstring Manager - Create and Manage Hotstrings
[Class] WinHook - Create Window Shell Hooks and Window Event Hooks

ntepa
Posts: 434
Joined: 19 Oct 2022, 20:52

Re: JSDoc Comments for Intellisense Help

Post by ntepa » 28 Nov 2023, 19:27

If you want your jsdoc in one place, you can use a separate file. Name it the same as your ahk file with .d.ahk extension.
Attachments
jsdoc.png
jsdoc.png (50.71 KiB) Viewed 1162 times

User avatar
FanaticGuru
Posts: 1907
Joined: 30 Sep 2013, 22:25

Re: JSDoc Comments for Intellisense Help

Post by FanaticGuru » 28 Nov 2023, 20:58

ntepa wrote:
28 Nov 2023, 19:27
If you want your jsdoc in one place, you can use a separate file. Name it the same as your ahk file with .d.ahk extension.

This looks extremely promising as I could then supply a separate file for people that use vscode.

But it did not work for me. In my setup I use the extension ah2 for AutoHotkey v2. I have tried saving the comment file as .d.ah2 and .d.ahk but neither worked.

Then I tried .ahk2.d.ahk and .ahk2.d.ah2 as I saw ahk2.d.ahk when googling.

Say I had a Autohotkey v2 file named Test.ah2, how would I name the comment file for it?

FG 
Hotkey Help - Help Dialog for Currently Running AHK Scripts
AHK Startup - Consolidate Multiply AHK Scripts with one Tray Icon
Hotstring Manager - Create and Manage Hotstrings
[Class] WinHook - Create Window Shell Hooks and Window Event Hooks

ntepa
Posts: 434
Joined: 19 Oct 2022, 20:52

Re: JSDoc Comments for Intellisense Help

Post by ntepa » 28 Nov 2023, 21:46

Naming the ahk file Test.ah2 and the jsdoc file Test.d.ahk worked for me.
Attachments
Test.ah2.png
Test.ah2.png (50.78 KiB) Viewed 1137 times

User avatar
FanaticGuru
Posts: 1907
Joined: 30 Sep 2013, 22:25

Re: JSDoc Comments for Intellisense Help

Post by FanaticGuru » 29 Nov 2023, 19:21

ntepa wrote:
28 Nov 2023, 21:46
Naming the ahk file Test.ah2 and the jsdoc file Test.d.ahk worked for me.

This did not work for me initially but after toying around in the settings.json file I got it to work.
Added:

Code: Select all

"files.associations": {
		"*.ah2": "ahk2"
	}
I already had ah2 recongnizing as v2 handled by AutoHotkey v2 Language Support and ahk as v1 handled by AutoHotkey Plus Plus (can't remember everything I did when initial setting up vscode) but adding this made the JSdoc file work.

I have tried to get Test.d.ah2 instead of Test.d.ahk to work with Test.ah2 but without any luck. I figure it is somewhere in AutoHotkey v2 Language Support files but can't find anything. Maybe @thqby could offer some help.

FG
Hotkey Help - Help Dialog for Currently Running AHK Scripts
AHK Startup - Consolidate Multiply AHK Scripts with one Tray Icon
Hotstring Manager - Create and Manage Hotstrings
[Class] WinHook - Create Window Shell Hooks and Window Event Hooks

Marium0505
Posts: 42
Joined: 11 May 2020, 20:45

Re: JSDoc Comments for Intellisense Help

Post by Marium0505 » 29 Nov 2023, 20:11

Personally, I like seeing the comments in the file itself, whether you have VS code or not.
The way I see it: The information itself is useful whether you have VS Code or not, as it gives very useful info about the functions etc.

I would recommend having JSDoc Comments directly above in the file itself, rather than a separate file.
I didn't use VS Code until just a few weeks ago, but been seeing these comments in code people have shared and found it very useful. It wasn't until I started using VS Code myself I understood what they were actually for, and that they were even more useful than I originally thought. :-P

User avatar
FanaticGuru
Posts: 1907
Joined: 30 Sep 2013, 22:25

Re: JSDoc Comments for Intellisense Help

Post by FanaticGuru » 29 Nov 2023, 21:47

Marium0505 wrote:
29 Nov 2023, 20:11
Personally, I like seeing the comments in the file itself, whether you have VS code or not.
The way I see it: The information itself is useful whether you have VS Code or not, as it gives very useful info about the functions etc.

Well, the best of both worlds is to comment the code using all the capabilities that the code allows then have a separate file to make IntelliSense help work for those that have it.

JSDoc commenting is much less flexible than normal commenting. Commenting only with the structure allowed by JSDoc is more difficult to read than what can be done using normal commenting. For example, JSDoc does not allow inline end of line like Inches := 12 ; Initialize to 1 Foot. JSDoc is designed to be parsed by another script, not necessarily what is best for a human to understand. It will often be very diffused through the code as a JSDoc comment must be placed in the code directly above every class/function/variable/parameter/property/method/etc. when it is initial encountered in the code. That can make the code look very disconnected with comment blocks dividing natural grouping of lines of code.

Basically all the built in IntelliSense help I get for every command in AutoHotkey is from a separate file where all that data is kept.

I am just starting to work with custom IntelliSense though so maybe my view will change. Custom IntelliSense is very helpful, even with my own library class/functions. I often have to open them to refresh my memory on parameters, properties and methods. IntelliSense avoids that with tooltips as I type.

FG
Hotkey Help - Help Dialog for Currently Running AHK Scripts
AHK Startup - Consolidate Multiply AHK Scripts with one Tray Icon
Hotstring Manager - Create and Manage Hotstrings
[Class] WinHook - Create Window Shell Hooks and Window Event Hooks

User avatar
thqby
Posts: 422
Joined: 16 Apr 2021, 11:18
Contact:

Re: JSDoc Comments for Intellisense Help

Post by thqby » 30 Nov 2023, 00:51

FanaticGuru wrote:
28 Nov 2023, 20:58
I have tried saving the comment file as .d.ah2 and .d.ahk but neither worked.
Only {file}.d.ahk files are automatically included.

User avatar
FanaticGuru
Posts: 1907
Joined: 30 Sep 2013, 22:25

Re: JSDoc Comments for Intellisense Help

Post by FanaticGuru » 30 Nov 2023, 13:52

thqby wrote:
30 Nov 2023, 00:51
FanaticGuru wrote:
28 Nov 2023, 20:58
I have tried saving the comment file as .d.ah2 and .d.ahk but neither worked.
Only {file}.d.ahk files are automatically included.

Is there somewhere in the code of your extension where that can be manually changed to include {file}.d.ah2 files?

Or better yet the associated file extension so Test.d.ahk would be used for a v1 script of Test.ahk and Test.d.ah2 for a v2 script of Test.ah2 assuming those are the extensions associated with each version.

FG
Hotkey Help - Help Dialog for Currently Running AHK Scripts
AHK Startup - Consolidate Multiply AHK Scripts with one Tray Icon
Hotstring Manager - Create and Manage Hotstrings
[Class] WinHook - Create Window Shell Hooks and Window Event Hooks

User avatar
thqby
Posts: 422
Joined: 16 Apr 2021, 11:18
Contact:

Re: JSDoc Comments for Intellisense Help

Post by thqby » 30 Nov 2023, 22:53

As far as I know there is no ahk v1 extension that supports .d.ahk files, you can associate *.d.ahk files with ahk2.

In addition, the v2 extension recognizes scripts with v1 features and switches the current language mode from ahk v2 to ahk v1. Therefore, the same filename suffix can be used.

Post Reply

Return to “Visual Studio Code”