[v2]v2-a108 and its documentation: errors, typos...

Share your ideas as to how the documentation can be improved.
User avatar
vvhitevvizard
Posts: 337
Joined: 25 Nov 2018, 10:15
Location: Russia

[v2]v2-a108 and its documentation: errors, typos...

31 Mar 2020, 10:35

1 year ago I side-stepped AHK v2 after discovering some disappointing stuff like "assume-global" for fat-arrow functions. But there r lotta good changes made since then (for current v2-a108 version). Performance and ahk.exe size optimization, more strict arguments check for built-in functions/methods, more consistency over all: #DllLoad, Buffer object, silently changed assume-local for fat-arrows(?)

my 10k+ lines script, written for v2-a100, yields lotta errors and unexpected behavior with v2-a108 so I started reading the official manual from the scratch. :D
And found quite a few typos/redundant stuff/errors (the post will be updated if I find more).

1.

Code: Select all

class class1{
	static func1(){
		t:=1
	}
	static func2()=>(t:=2)
}

t:="A: not changed"
class1.func1() ;global var: "not changed"
msgbox(t)
t:="B: not changed"
class1.func2()
;v2-a100: NOT EXPECTED: global var changed to: "2"
;v2-a108: OK, "not changed", fat-arrow func is assume-local!!
msgbox(t)
but the documentation still says:
https://lexikos.github.io/v2/docs/Variables.htm#fat-arrow
The function is assume-local if it is nested inside another function, otherwise it is assume-global.

EDIT: oh nvm, methods r OK, but not-nested functions r assume-global still. :(

Code: Select all

t:="C: not changed"
func3()=>(t:=3)
func3()
msgbox(t) ; =3, changed :(
2.
https://lexikos.github.io/v2/docs/commands/BufferAlloc.htm
FillByte: If omitted, the memory of the buffer is not initialized; the value of each byte is arbitrary.
but:
Remarks: All bytes within the buffer are zero-initialized.

3.
https://lexikos.github.io/v2/docs/Objects.htm#Usage_Arrays_of_Arrays
array should be 4 x 3 (__new method accepts (x, y))
grid := Array2D.new(3, 4) ;3 x 4, should be 4,3

4.
https://lexikos.github.io/v2/docs/commands/DllCall.htm#ExMouseSpeed
example 6 gives weird error "type mismatch at line 12"
also line 12: 0x71 should be replaced with SPI_SETMOUSESPEED for consistency

5.
https://lexikos.github.io/v2/docs/objects/Buffer.htm
ClipboardAll returns a sub-type of Buffer, also named ClipboardAll.
swagfag
Posts: 3763
Joined: 11 Jan 2017, 17:59

Re: v2-a108 and its documentation: errors, typos...

31 Mar 2020, 11:14

1. no comment
2. it doesnt zero initialize
3. if anything, the loops should be swapped around

Code: Select all

Loop grid.Height {
    y := A_Index
    Loop grid.Width {
        x := A_Index
and call the args w/h or col/row instead of x/y
4. should be:

Code: Select all

SPI_GETMOUSESPEED := 0x70
SPI_SETMOUSESPEED := 0x71

F1::
; Retrieve the current speed so that it can be restored later:
DllCall("SystemParametersInfo", "UInt", SPI_GETMOUSESPEED, "UInt", 0, "Ptr*", OrigMouseSpeed := 0, "UInt", 0)
; Now set the mouse to the slower speed specified in the next-to-last parameter (the range is 1-20, 10 is default):
DllCall("SystemParametersInfo", "UInt", SPI_SETMOUSESPEED, "UInt", 0, "Ptr", 3, "UInt", 0)
KeyWait "F1"  ; This prevents keyboard auto-repeat from doing the DllCall repeatedly.
return

F1 up::DllCall("SystemParametersInfo", "UInt", SPI_SETMOUSESPEED, "UInt", 0, "Ptr", OrigMouseSpeed, "UInt", 0)  ; Restore the original speed.
5. ok
User avatar
vvhitevvizard
Posts: 337
Joined: 25 Nov 2018, 10:15
Location: Russia

Re: v2-a108 and its documentation: errors, typos...

31 Mar 2020, 11:32

@swagfag, thanks for quick reply. I posted here cuz the documentation seems to be not edited since the recent .exe changes...
e.g. 2. has that text persisting: "Remarks: All bytes within the buffer are zero-initialized." I highlighted those text parts in red. :D

concerning 1.: not nested fat-arrow functions r essentially just functions. and functions r assume-local:

Code: Select all

func1()
{
    global  ;override assume-local here
    MyGlobal := 33  ; Assigns 33 to a global variable, first creating the variable if necessary.
    local x, y:=0, z  ; Local variables must be declared in this mode, otherwise they would be assumed global.
}
having fat-arrow functions as assume-global is prone to mistakes, all the functions/methods should be agnostic by default to user-defined global variables.
Last edited by vvhitevvizard on 31 Mar 2020, 12:59, edited 2 times in total.
User avatar
vvhitevvizard
Posts: 337
Joined: 25 Nov 2018, 10:15
Location: Russia

Re: v2-a108 and its documentation: errors, typos...

31 Mar 2020, 12:52

6.

Code: Select all

msgbox("here")

class class1{
	static D:=8
	static H:=()=>(0)
	static T:=()=>(0)
}
this code just silently fails. it never proceeds to msgbox line. but if u try to comment ANY 1 of the 3 static statement lines, it manages to proceed to msgbox line.
I know the correct syntax now is static H:=()=>(0) -> static H()=>(0). But having some error reporting would be great for ones trying to upgrade from previous v2 alpha versions :D
User avatar
vvhitevvizard
Posts: 337
Joined: 25 Nov 2018, 10:15
Location: Russia

Re: v2-a108 and its documentation: errors, typos...

31 Mar 2020, 13:23

7.

Error: This value of type "Array" has no method named "Count"

Code: Select all

;v2-a100 valid code:
s:=[]
msgbox(s.Count())
There is no mentioning that Object/Array method "Count" was removed/replaced in the summary of changes https://autohotkey.com/boards/viewtopic.php?f=37&t=2120&start=40
I presume its a property Length now(?)
User avatar
Ragnar
Posts: 306
Joined: 30 Sep 2013, 15:25

Re: v2-a108 and its documentation: errors, typos...

31 Mar 2020, 13:29

Please use the subforum Suggestions on documentation improvements from now on and create a new topic per issue, so it can be better managed and discussed.

I will include your suggestions in the docs, if reasonable, and submit them on GitHub. This may take some time until the changes are finally visible in the docs, as Lexikos seems to be very busy at the moment.
swagfag
Posts: 3763
Joined: 11 Jan 2017, 17:59

Re: v2-a108 and its documentation: errors, typos...

31 Mar 2020, 13:44

6. is not an error, rather a straight up crash. script.cpp:7673 g->CurrentFunc = g->CurrentFunc->mOuterFunc; dereferenced nullptr
7.
Spoiler
and the array documentation itself
User avatar
Ragnar
Posts: 306
Joined: 30 Sep 2013, 15:25

Re: v2-a108 and its documentation: errors, typos...

31 Mar 2020, 15:00

Number 5 is not a typo. Example: MsgBox Type(ClipboardAll())
User avatar
vvhitevvizard
Posts: 337
Joined: 25 Nov 2018, 10:15
Location: Russia

Re: v2-a108 and its documentation: errors, typos...

01 Apr 2020, 00:33

ty @Ragnar! But then for 5. the documentation's statement has to be changed to mention Type's return string for ClipboardAll. the whole manual has to be as crystal clear as possible. the final goal is to reduce the learning curve. Right now its pretty much steep for ones coming from AHK v1 and previous AHK v2 alpha versions =)

Also recent built-in objects and functions definitely require more simple examples of usage in the documentation, like this one for Map (example by @Helgef):

Code: Select all

;create a map with a customizable default value:
class m extends map {
	__new(default := 0) => this.default := default
	__item[key] => this.has(key) ? base[key] : this.default
}

Return to “Suggestions on documentation improvements”

Who is online

Users browsing this forum: No registered users and 1 guest