Page 1 of 31

Suggestions on documentation improvements

Posted: 14 Jan 2014, 14:42
by Guest
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/

Re: Suggestions on documentation improvements

Posted: 15 Jan 2014, 01:55
by lexikos
#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:

Code: Select all

<a href="../AutoHotkey.htm">-- Home --</a>
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.

Onmessage() - optional parameters, ByRef parameters

Posted: 19 Jan 2014, 14:43
by trismarck
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.

Code: Select all

fun(ByRef a) {
}
fun2(a := 3) {
}
fun3(ByRef a, ByRef b, c, d, e := 5) {
}
fun4(ByRef a, ByRef b, c, d, ByRef e := 5) {
}
MsgBox, % OnMessage(12345, "fun") ; fun
MsgBox, % OnMessage(23456, "fun2") ; fun2
MsgBox, % OnMessage(34567, "fun3") ; fun3 (4 param limit works)
MsgBox, % OnMessage(45678, "fun4") ; fun4

ExitApp

Re: Suggestions on documentation improvements

Posted: 19 Jan 2014, 17:00
by lexikos
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.

Re: Suggestions on documentation improvements

Posted: 17 Feb 2014, 15:07
by julka
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.

Re: Suggestions on documentation improvements

Posted: 30 Mar 2014, 03:56
by vasili111
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.

Re: Suggestions on documentation improvements

Posted: 08 May 2014, 22:17
by GeekDude
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]"?

Re: Suggestions on documentation improvements

Posted: 09 May 2014, 02:53
by just me
From the Clipboard section of the current help file (1.1.15.00):
Clipboard.PNG
Clipboard.PNG (4.1 KiB) Viewed 14829 times
The additional description in parenthesises is too weak and pale.

Re: Suggestions on documentation improvements

Posted: 10 May 2014, 23:33
by lexikos
It is intended to be de-emphasized, like the version number notes ([v1.x.yy+]).

Re: Suggestions on documentation improvements

Posted: 15 May 2014, 10:49
by Coco
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:

Code: Select all

fn(this) {
	static a := {__Delete:"fn"}
	static b := new a
	
	MsgBox % (this.base == a) ; returns false, 'a' got released
}

fn2(this) {
	static d := {__Delete:"fn2"}
	static c := new d

	MsgBox % (this.base == d) ; returns true, 'd' still exists
}

MsgBox
ExitApp

Re: Suggestions on documentation improvements

Posted: 17 May 2014, 23:55
by lexikos
It is left undocumented for a reason; scripts should not rely on it.

Re: Suggestions on documentation improvements

Posted: 28 May 2014, 20:07
by Barney
The section The WinTitle Parameter & the Last Found Window > The "Last Found" Window
misses to mention #IfWinActive / #IfWinExist

Re: Suggestions on documentation improvements

Posted: 17 Jul 2014, 05:04
by trismarck
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.

Re: Suggestions on documentation improvements

Posted: 17 Jul 2014, 10:25
by joedf
+1

Re: Suggestions on documentation improvements

Posted: 17 Jul 2014, 16:31
by lexikos
Process Close does not set A_LastError.

Re: Suggestions on documentation improvements

Posted: 17 Jul 2014, 18:36
by trismarck
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.

Code: Select all

Process, Close, 39847338
MsgBox, % ret "`n" ErrorLevel "`n" A_LastError ; "" 0 0
So to reiterate: perhaps Process, Close _could_ set A_LastError upon not being able to open the process / terminate the process?

Re: Suggestions on documentation improvements

Posted: 17 Jul 2014, 19:02
by joedf
+1

Re: Suggestions on documentation improvements

Posted: 17 Jul 2014, 22:03
by lexikos
How often does it fail, and how often would the script be designed to handle that failure?

Re: Suggestions on documentation improvements

Posted: 18 Jul 2014, 05:47
by trismarck
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.

Posted: 21 Jul 2014, 09:25
by nnnik
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.