[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
Guest
Posts: 57
Joined: 17 Oct 2013, 02:32

[Archived, Locked] Suggestions on documentation improvements

14 Jan 2014, 14:42

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/
lexikos
Posts: 9494
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

15 Jan 2014, 01:55

#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.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Onmessage() - optional parameters, ByRef parameters

19 Jan 2014, 14:43

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
lexikos
Posts: 9494
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

19 Jan 2014, 17:00

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.
julka
Posts: 14
Joined: 06 Feb 2014, 02:31

Re: Suggestions on documentation improvements

17 Feb 2014, 15:07

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.
vasili111
Posts: 747
Joined: 21 Jan 2014, 02:04
Location: Georgia

Re: Suggestions on documentation improvements

30 Mar 2014, 03:56

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.
geek
Posts: 1051
Joined: 02 Oct 2013, 22:13
Location: GeekDude
Contact:

Re: Suggestions on documentation improvements

08 May 2014, 22:17

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]"?
just me
Posts: 9406
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Suggestions on documentation improvements

09 May 2014, 02:53

From the Clipboard section of the current help file (1.1.15.00):
Clipboard.PNG
Clipboard.PNG (4.1 KiB) Viewed 24609 times
The additional description in parenthesises is too weak and pale.
lexikos
Posts: 9494
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

10 May 2014, 23:33

It is intended to be de-emphasized, like the version number notes ([v1.x.yy+]).
Coco
Posts: 771
Joined: 29 Sep 2013, 20:37
Contact:

Re: Suggestions on documentation improvements

15 May 2014, 10:49

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
lexikos
Posts: 9494
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

17 May 2014, 23:55

It is left undocumented for a reason; scripts should not rely on it.
User avatar
Barney
Posts: 55
Joined: 28 May 2014, 20:03
Location: Germany

Re: Suggestions on documentation improvements

28 May 2014, 20:07

The section The WinTitle Parameter & the Last Found Window > The "Last Found" Window
misses to mention #IfWinActive / #IfWinExist
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

17 Jul 2014, 05:04

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.
lexikos
Posts: 9494
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

17 Jul 2014, 16:31

Process Close does not set A_LastError.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

17 Jul 2014, 18:36

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?
Last edited by trismarck on 18 Jul 2014, 05:54, edited 1 time in total.
lexikos
Posts: 9494
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

17 Jul 2014, 22:03

How often does it fail, and how often would the script be designed to handle that failure?
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

18 Jul 2014, 05:47

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.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Add Lazy quantifiers to Regex Quick Reference.

21 Jul 2014, 09:25

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.
Recommends AHK Studio

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 14 guests