AutoHotkey Community

I thought it would be nice to have a "Suggestions on documentation improvements" thread on AHKScript as well so here goes

All very minor:

1) https://github.com/Lexikos/AutoHotkey_L ... ex.htm#L20
The Forum link goes to http://www.auto-hotkey.com/boards/ suggest to change to ahkscript.org

2) http://www.ahkscript.org/docs/misc/Macros.htm
The -- Home -- link goes to http://www.auto-hotkey.com/ suggest to change to ahkscript.org

3) http://www.ahkscript.org/docs/AHKL_Features.htm
double home - once is probably enough :-)

Notes:
1) For those with Github expertise: https://github.com/Lexikos/AutoHotkey_L-Docs
2) The original http://www.autohotkey.com/board/topic/2 ... rovements/

#1 isn't part of the documentation. It is the front page of l.autohotkey.net, which is soon becoming obsolete.

#2 - someone must have been playing. In my copy of the documentation, the source of that link is: So this change will be reverted when the documentation is uploaded after the next release.

#3 - tank added the bold navigation links to all pages via find and replace. I will remove the original link for future updates.

It looks like it's partially undocumented that OnMessage() _does_ support optional / ByRef parameters.
Also, how does the function behave for ByRef parameters / for optional parameters 5,6,7 / optional _and_ ByRef parameters 5,6,7 ? (~do they get a preset value or are initialized with "")

Documentation wrote:If FunctionName is non-blank: If MsgNumber is already being monitored, it returns the name of that function then puts the new function into effect. Otherwise, it assigns FunctionName to monitor MsgNumber then returns the same FunctionName. In either case, a blank value is returned upon failure. Failure occurs when FunctionName: 1) does not exist (perhaps due to missing quotes around FunctionName); 2) accepts more than four parameters; or 3) has any ByRef or optional parameters. It will also fail if the script attempts to monitor a new message when there are already 500 messages being monitored.

Revision 60 - September 24, 2010 wrote:Changed: OnMessage functions now tolerate optional and ByRef parameters.

Right, 3) is obsolete.

Also, how does the function behave for ByRef parameters / for optional parameters 5,6,7 / optional _and_ ByRef parameters 5,6,7 ? (~do they get a preset value or are initialized with "")

It behaves normally, as per the documentation.

Reference from A_GuiWidth and A_GuiHeight to WinGetPos would be helpful.
I remember myself struggling to get gui's width and height, the joy when I thought I found built-in variables and the grieve, when realized they only work if Gui is moved.

I know built-in vars would be hard to implement (actually, impossible), so reference to WinGetPos would be nice.

I think all topics which are in folder Objects of AutoHotkey documentation needs big improvement. Unlikely other documentation of AutoHotkey it is very hard (I would say impossible) to understand it for those, whose first programming language is AutoHotkey.

The process command is listed as "Process, Cmd, PID-or-Name [, Param3]", but in the description of PID-or-Name, it is said that it is optional/can be left blank "It can also be left blank to change the priority of the script itself."

Perhaps change it to "Process, Cmd, [PID-or-Name , Param3]"?

From the Clipboard section of the current help file (1.1.15.00):
The additional description in parenthesises is too weak and pale.

It is intended to be de-emphasized, like the version number notes ([v1.x.yy+]).

Currently the docs say(under 'Objects'):

Docs wrote:Although references in static and global variables are released automatically when the program exits...

I propose to add/insert something along these lines:

Static variables(within the same function scope) containing object references are freed alphabetically.

As observed below:

It is left undocumented for a reason; scripts should not rely on it.

The section The WinTitle Parameter & the Last Found Window > The "Last Found" Window
misses to mention #IfWinActive / #IfWinExist

Perhaps it could be documented that Process, Close sets the A_LastError variable.

MSDN wrote:If the function fails, the return value is zero. To get extended error information, call GetLastError.

Related.

+1

Process Close does not set A_LastError.

Indeed it doesn't, as the LastError member has to be set explicitly for A_LastError to be set. Up to this point I've thought that A_LastError just calls GetLastError() whenever encountered, but this is not the case - A_LastError has to be set explicitly by a given AHK command. //edit: that would be pointless - when a call to GetLastError would be made, the last error variable that the system stores would be out of context long time ago. So to reiterate: perhaps Process, Close _could_ set A_LastError upon not being able to open the process / terminate the process?

+1

How often does it fail, and how often would the script be designed to handle that failure?

On LastError:
It seems to be that A_LastError is set in general only for file and registry related commands and for a few special commands/functions like DllCall or Run. For _other_ commands or functions, because the error occurs infrequently or the reason behind the error is not that important, it is the user that is responsible for writing a custom function if the user wants to handle the error explicitly.
On Process, Close:
Like a file or a registry, the process seems to be one of the most important parts of the system. OTOH, A_LastError would be more relevant if the process _was_ closed in a scenario where it shouldn't. If the process doesn't close, then perhaps the information that the process just wasn't closed is sufficient.
WinClose doesn't set ErrorLevel and WinWaitClose sets the Errorlevel but the only reason for that is the timeout. So there seems to be no built-in way to tell of why a given process was not closed.
Another thought would be: what should the Autohotkey user do, if Process, Close has failed to close the process and the user is certain that the process exists (there is no other more forceful command to kill that process). The user would be happy to at least know, why the process didn't close.
But overall, I agree that checking the last error of Process, Close would be rare (and if there are permissions / privilege levels involved, Process, Close will not be the only command that will fail).
Thanks.

Add Lazy quantifiers to Regex Quick Reference.
In the past I often have searched for a way to use U) without using U).
The lazy Quantifier would solve this problem, however they are not documented.