Page 11 of 35

Re: Suggestions on documentation improvements

Posted: 31 Jan 2017, 20:00
by iPhilip
This part of the documentation about Objects states:
__Delete is not called for any object which has the key "__Class". Class objects have this key by default.
The example below shows that__Delete is also not called if the object contains a bound method:

Code: Select all

counter := new SecondCounter
Msgbox, % counter.HasKey("__Class") "`n" SecondCounter.HasKey("__Class")
counter.Start()
Sleep 5000
counter.Stop()
Sleep 2000
counter =   ; I would expect a ToolTip to show up as a result of this operation
Sleep 2000
Return

; From https://autohotkey.com/docs/commands/SetTimer.htm#ExampleClass

class SecondCounter {
   __New() {
     this.interval := 1000
     this.count := 0
     this.timer := ObjBindMethod(this, "Tick")   ; of this.Tick.Bind(this)
   }
   Start() {
      timer := this.timer
      SetTimer % timer, % this.interval
      ToolTip % "Counter started"
   }
   Stop() {
      timer := this.timer
      SetTimer % timer, Off
      ToolTip % "Counter stopped at " this.count
   }
   Tick() {
      ToolTip % ++this.count
   }
   ; This function is the only addition to the example
   __Delete() {
      ToolTip Deleting object ...
   }
}
I would recommend that the documentation be updated to reflect that, i.e.
__Delete is not called for any object which has the key "__Class" or contains a bound method. Class objects have this key by default.
Cheers!

Re: Suggestions on documentation improvements

Posted: 01 Feb 2017, 03:18
by Helgef
It was quite well explained by kon that the quote from the docs is not relevant for this example. However, it is not a bad idea to include this in the fourth example from SetTimer, to showcase relevant usage of SetTimer,f,delete. One could also link to such an extended example from the __delete() docs.

Finally, you bringing this up in the first place was very useful for me, so thanks, and

Cheers!

Re: Suggestions on documentation improvements

Posted: 01 Feb 2017, 12:41
by iPhilip
Hi Helgef,

I agree that the quote from the docs is not relevant. What I am trying to say is that the docs are incomplete. In my opinion, it would be useful to alert the user of a condition where __Delete is not called.

Cheers!

Re: Suggestions on documentation improvements

Posted: 01 Feb 2017, 19:20
by lexikos
__Delete is called when the object is being deleted. The object is not being deleted in this case, so there is no reason to think that __Delete should be called.

The documentation already covers the issues with circular references.

Re: Suggestions on documentation improvements

Posted: 01 Feb 2017, 19:34
by Helgef
iPhilip wrote:Hi Helgef,

I agree that the quote from the docs is not relevant. What I am trying to say is that the docs are incomplete. In my opinion, it would be useful to alert the user of a condition where __Delete is not called.

Cheers!
I understand your intentions. But it would be misplaced at your suggested location, and it is not exclusively related to bound funcs, consider,

Code: Select all

class SecondCounter {
   __New() {
	;[...]
	ObjBindMethod(this, "Tick")
	this.that:=this			; Another self-reference that needs to be deleted before __delete() can be called	
   }

Re: Suggestions on documentation improvements

Posted: 01 Feb 2017, 19:40
by iPhilip
Hi lexikos,

I am confused by your statement:
lexikos wrote:... The object is not being deleted in this case, so there is no reason to think that __Delete should be called.
Doesn't the above line

Code: Select all

counter =
delete the object?

Re: Suggestions on documentation improvements

Posted: 01 Feb 2017, 21:35
by guest3456
https://autohotkey.com/docs/Objects.htm ... ng_Objects

although i don't see any harm with docs being more verbose rather than concise. repetition is not a Bad Thing when it comes to docs. it just makes information easier to find and reinforces the learning of the reader, and as a result reduces help questions in the forum :)

Re: Suggestions on documentation improvements

Posted: 02 Feb 2017, 02:38
by iPhilip
guest3456 wrote:https://autohotkey.com/docs/Objects.htm ... ng_Objects

although i don't see any harm with docs being more verbose rather than concise. repetition is not a Bad Thing when it comes to docs. it just makes information easier to find and reinforces the learning of the reader, and as a result reduces help questions in the forum :)
Hi guest3456,

Could you clarify what you mean by the above? I am not sure if it's in reference to my posting.

Thank you.

Re: Suggestions on documentation improvements

Posted: 02 Feb 2017, 13:21
by kon
iPhilip wrote:Doesn't the above line

Code: Select all

counter =
delete the object?
Only if that is the only reference to the object.
- https://en.wikipedia.org/wiki/Reference_counting

Consider the following.

Code: Select all

Counter := []
Counter := ""
ListVars
MsgBox, % IsObject(Counter)

Counter := []
OtherVar := Counter
Counter := ""
ListVars
MsgBox, % IsObject(OtherVar)  ; Object is not freed because a reference still exists.
SetTimer stores a reference to the object internally. That is why you need to delete that reference, and all other references you have to the object, before it is freed.

Re: Suggestions on documentation improvements

Posted: 02 Feb 2017, 13:28
by guest3456
@iPhilip:
the link was for your reading pleasure

@kon:
SetTimer,, Delete ?

Re: Suggestions on documentation improvements

Posted: 02 Feb 2017, 13:44
by iPhilip
Thank you, kon! Your post really helped me understand the issue. More specifically, I learned that:
  1. Deleting an object requires freeing all its references (now I understand guest3456's reference to freeing objects)
  2. SetTimer stores a reference to objects internally and that reference is freed only with a SetTimer, Label, Delete command
Thank you all for your contribution to my learning.

Cheers!

Re: Suggestions on documentation improvements

Posted: 03 Feb 2017, 19:54
by iPhilip
Based on the above discussion, I would recommend the following clarification to the documentation language on the Objects page.
When an object is destroyed, including freeing all its references to release the object, __Delete is called. Note that, if the label name in a SetTimer command is a reference to a function object that is part of the object, the reference can only be freed with a SetTimer, Label, Delete command.

Re: Suggestions on documentation improvements

Posted: 13 Feb 2017, 19:41
by glycoversi
I've been browsing the AHK documentation pages alot and wondered how feasable it would be to have a collapsable comment section for each section of example code (or just one per page even).

I feel this would be an extremely efficient way to ask/answer questions on very specific areas of AHK and clarify the meaning of the scripts as well for all page visitors.

I know this is probably an enormous task, but just figured I'd throw it out there because I always have small questions that I'm sure could be very quickly answer with such a technology. Until then, I'll keep browsing the forums and documentation!

Re: Suggestions on documentation improvements

Posted: 13 Feb 2017, 21:26
by guest3456
glycoversi wrote:I've been browsing the AHK documentation pages alot and wondered how feasable it would be to have a collapsable comment section for each section of example code (or just one per page even).

I feel this would be an extremely efficient way to ask/answer questions on very specific areas of AHK and clarify the meaning of the scripts as well for all page visitors.

I know this is probably an enormous task, but just figured I'd throw it out there because I always have small questions that I'm sure could be very quickly answer with such a technology. Until then, I'll keep browsing the forums and documentation!
This is a great idea, and something that PHP does. At the bottom of all of their online docs pages, users can add their own comments, and quirks, and gotcha's. Actually now that I think of it, even MSDN has this

Re: Suggestions on documentation improvements

Posted: 14 Feb 2017, 01:09
by glycoversi
guest3456 wrote:
glycoversi wrote:I've been browsing the AHK documentation pages alot and wondered how feasable it would be to have a collapsable comment section for each section of example code (or just one per page even).

I feel this would be an extremely efficient way to ask/answer questions on very specific areas of AHK and clarify the meaning of the scripts as well for all page visitors.

I know this is probably an enormous task, but just figured I'd throw it out there because I always have small questions that I'm sure could be very quickly answer with such a technology. Until then, I'll keep browsing the forums and documentation!
This is a great idea, and something that PHP does. At the bottom of all of their online docs pages, users can add their own comments, and quirks, and gotcha's. Actually now that I think of it, even MSDN has this
No way! What websites? Don't know ant PHP but would love to see the implementation.

Re: Suggestions on documentation improvements

Posted: 14 Feb 2017, 08:55
by guest3456
glycoversi wrote:No way! What websites? Don't know ant PHP but would love to see the implementation.
http://php.net/manual/en/control-structures.elseif.php

Re: Suggestions on documentation improvements

Posted: 21 Feb 2017, 12:52
by guest3456
https://autohotkey.com/docs/commands/_EscapeChar.htm

should list `s as an escape sequence

Re: Suggestions on documentation improvements

Posted: 21 Feb 2017, 13:13
by iPhilip
What does the `s escape sequence generate?

Re: Suggestions on documentation improvements

Posted: 21 Feb 2017, 13:15
by guest3456
Shit, I thought it generated A_Space, but apparently not. But I'm certain I saw it listed somehwere in the docs..

here:

https://autohotkey.com/docs/commands/_IfWinActive.htm
The escape sequences `s and `t may be used if leading or trailing spaces/tabs are needed in one of #IfWin's parameters.
maybe it only works for that command...?

Re: Suggestions on documentation improvements

Posted: 21 Feb 2017, 14:33
by joedf
I think you might be right... It seems `s is only valid for that command.