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/
[Archived, Locked] Suggestions on documentation improvements
Re: Suggestions on documentation improvements
#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.
#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>
#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
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 "")
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
Right, 3) is obsolete.
It behaves normally, as per the documentation.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 "")
Re: Suggestions on documentation improvements
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 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
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.
DRAKON-AutoHotkey: Visual programming for AutoHotkey.
Re: Suggestions on documentation improvements
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]"?
Perhaps change it to "Process, Cmd, [PID-or-Name , Param3]"?
Re: Suggestions on documentation improvements
From the Clipboard section of the current help file (1.1.15.00):
The additional description in parenthesises is too weak and pale.
The additional description in parenthesises is too weak and pale.
Re: Suggestions on documentation improvements
It is intended to be de-emphasized, like the version number notes ([v1.x.yy+]).
Re: Suggestions on documentation improvements
Currently the docs say(under 'Objects'):
I propose to add/insert something along these lines:Docs wrote:Although references in static and global variables are released automatically when the program exits...
As observed below:Static variables(within the same function scope) containing object references are freed alphabetically.
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
It is left undocumented for a reason; scripts should not rely on it.
Re: Suggestions on documentation improvements
The section The WinTitle Parameter & the Last Found Window > The "Last Found" Window
misses to mention #IfWinActive / #IfWinExist
misses to mention #IfWinActive / #IfWinExist
Re: Suggestions on documentation improvements
Perhaps it could be documented that Process, Close sets the A_LastError variable.
Related.MSDN wrote:If the function fails, the return value is zero. To get extended error information, call GetLastError.
Re: Suggestions on documentation improvements
+1
Windows 10 x64 Professional, Intel i5-8500, NVIDIA GTX 1060 6GB, 2x16GB Kingston FURY Beast - DDR4 3200 MHz | [About Me] | [About the AHK Foundation] | [Courses on AutoHotkey]
[ASPDM - StdLib Distribution] | [Qonsole - Quake-like console emulator] | [LibCon - Autohotkey Console Library]
Re: Suggestions on documentation improvements
Process Close does not set A_LastError.
Re: Suggestions on documentation improvements
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?
Code: Select all
Process, Close, 39847338
MsgBox, % ret "`n" ErrorLevel "`n" A_LastError ; "" 0 0
Last edited by trismarck on 18 Jul 2014, 05:54, edited 1 time in total.
Re: Suggestions on documentation improvements
+1
Windows 10 x64 Professional, Intel i5-8500, NVIDIA GTX 1060 6GB, 2x16GB Kingston FURY Beast - DDR4 3200 MHz | [About Me] | [About the AHK Foundation] | [Courses on AutoHotkey]
[ASPDM - StdLib Distribution] | [Qonsole - Quake-like console emulator] | [LibCon - Autohotkey Console Library]
Re: Suggestions on documentation improvements
How often does it fail, and how often would the script be designed to handle that failure?
Re: Suggestions on documentation improvements
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.
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.
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.
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.
Recommends AHK Studio
Return to “Suggestions on Documentation Improvements”
Who is online
Users browsing this forum: No registered users and 3 guests