JSDoc Comments for Intellisense Help

[FanaticGuru]

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

[ntepa]

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.

[FanaticGuru]

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 

[ntepa]

Naming the ahk file Test.ah2 and the jsdoc file Test.d.ahk worked for me.

[FanaticGuru]

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

[Marium0505]

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.

[FanaticGuru]

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

[thqby]

I have tried saving the comment file as .d.ah2 and .d.ahk but neither worked.

Only {file}.d.ahk files are automatically included.

[FanaticGuru]

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

[thqby]

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.