How to comment script notes like /** @param ? Find list of formatting for syntax?

[sashaatx]

In various classes, I'm trying to format my library notes properly and I cannot find in the docs how to format.

Example, https://github.com/thqby/ahk2_lib/blob/master/WebSocket.ahk

Code: Select all

/**************   these dont get highlighted  **********************
 * @author thqby
 * @date 2023/01/16
 * @version 1.0.2
 ***********************************************************************/
 
 
 
 	; @param gets highlighted and {string}, but sometimes not. ? 
 	
 	
 	/**
	 * @param {String} Url the url of websocket
	 * @param {Object} Events an object of `{data:(this, buf)=>void,message:(this, msg)=>void,close:(this, status, reason)=>void}`
	 * @param {Integer} Async Use asynchronous mode
	 * @param {Object|Map|String} Headers Request header
	 */

why do the words @param and one word after param get highlighted, is param a specific word the script it looking for?
@author doesn't get highlighted, etc

searched the entire docs, no dice. would love a list or method for this. help? Thanks!

[gregster]

So your question is about the syntax highlighting in our forum code boxes? Or on github?
For me, nothing in the box above gets highlighted, it's all greyed out (on github, I don't see any highlighted @param either) - but that may vary depending on the chosen forum theme, because there have been some adjustments for readability.
Anyway, the syntax highlighting in the forum code boxes is surely not perfect. You might have noticed that all code boxes still link to the v1 docs. This still has to be worked on. Which forum theme are you using?

The linked github page still seems to follow the v1 highlighting as well, so that some areas at the top and further down are greyed out which shouldn't be. In v1, */ only worked when at the start of a line. In v2, */ can also appear at the end of a line to determine the end of a multi-line comment section. This obviously causes some wrong highlighting on the linked github page.

Individual users might see different effects anyway, in their respective editors - so I wouldn't worry too much about it. You can't account for every non-perfect syntax highlighting which may exist somewhere.

[sashaatx]

So your question is about the syntax highlighting in our forum code boxes? Or on github?
For me, nothing in the box above gets highlighted, it's all greyed out (on github, I don't see any highlighted @param either) - but that may vary depending on the chosen forum theme, because there have been some adjustments for readability.
Anyway, the syntax highlighting in the forum code boxes is surely not perfect. You might have noticed that all code boxes still link to the v1 docs. This still has to be worked on. Which forum theme are you using?

The linked github page still seems to follow the v1 highlighting as well, so that some areas at the top and further down are greyed out which shouldn't be. In v1, */ only worked when at the start of a line. In v2, */ can also appear at the end of a line to determine the end of a multi-line comment section. This obviously causes some wrong highlighting on the linked github page.

Individual users might see different effects anyway, in their respective editors - so I wouldn't worry too much about it. You can't account for every non-perfect syntax highlighting which may exist.

Thanks for the reply. I didn't think of where I was at. I'll be more descriptive.

So- this is sublime text syntax highlighting for v2 and syntax highlighting for vscode (official)

On hover text, it's very explicit the way you see this syntax, @params, vs @prop

Im just curious if there's a bank of keywords or syntax patterns I can follow. It's bugging me lol.

image.png (117.29 KiB) Viewed 1580 times

image.png (216.52 KiB) Viewed 1580 times

[gregster]

I don't know who the maintainers of these specific syntax highlightings are - but I would address them, if you have suggestions to improve their work.

I moved this topic to the 'Editors' subforum, which might fit better than the v2 help subforum.

[boiler]

So- this is sublime text syntax highlighting for v2 and syntax highlighting for vscode (official)

There is no “official” editor for AHK, nor is there an official extension/plug-in for any of the editors. Any syntax highlighting approaches are simply created by users on their own with no official connection to the AHK developers.

The rules of what gets highlighted in certain colors is not simply driven by keywords. It is more often driven by the context in which a token is used. That’s why it will be different in different situations. As gregster said, it’s the individual who created the extension/plug-in you are using that made the choices on how things will be highlighted. You need to identify exactly which plug-in(s) by namee/author that you are using, or else your questions are really not directed to anyone that can answer.

I thought at one point, lexikos generated a list of v2 keywords to aid those implementing syntax highlighting, but I can’t find it in any case.

[sashaatx]

So- this is sublime text syntax highlighting for v2 and syntax highlighting for vscode (official)

There is no “official” editor for AHK, nor is there an official extension/plug-in for any of the editors. Any syntax highlighting approaches are simply created by users on their own with no official connection to the AHK developers.

The rules of what gets highlighted in certain colors is not simply driven by keywords. It is more often driven by the context in which a token is used. That’s why it will be different in different situations. As gregster said, it’s the individual who created the extension/plug-in you are using that made the choices on how things will be highlighted. You need to identify exactly which plug-in(s) by namee/author that you are using, or else your questions are really not directed to anyone that can answer.

I thought at one point, lexikos generated a list of v2 keywords to aid those implementing syntax highlighting, but I can’t find it in any case.

https://github.com/thqby/vscode-autohotkey2-lsp

thqby
/
vscode-autohotkey2-lsp

[ntepa]

why do the words @param and one word after param get highlighted, is param a specific word the script it looking for?

The one word after @param is the parameter name. The words after that is the description of the parameter.
You won't find anything about @param in the AHK docs. This type of annotation is JSDoc.