[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
iPhilip
Posts: 802
Joined: 02 Oct 2013, 12:21

Re: Suggestions on documentation improvements

31 Jan 2017, 20:00

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!
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

01 Feb 2017, 03:18

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!
iPhilip
Posts: 802
Joined: 02 Oct 2013, 12:21

Re: Suggestions on documentation improvements

01 Feb 2017, 12:41

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!
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
lexikos
Posts: 9560
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

01 Feb 2017, 19:20

__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.
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

01 Feb 2017, 19:34

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	
   }
iPhilip
Posts: 802
Joined: 02 Oct 2013, 12:21

Re: Suggestions on documentation improvements

01 Feb 2017, 19:40

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?
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

01 Feb 2017, 21:35

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 :)

iPhilip
Posts: 802
Joined: 02 Oct 2013, 12:21

Re: Suggestions on documentation improvements

02 Feb 2017, 02:38

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.
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
kon
Posts: 1756
Joined: 29 Sep 2013, 17:11

Re: Suggestions on documentation improvements

02 Feb 2017, 13:21

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.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

02 Feb 2017, 13:28

@iPhilip:
the link was for your reading pleasure

@kon:
SetTimer,, Delete ?

iPhilip
Posts: 802
Joined: 02 Oct 2013, 12:21

Re: Suggestions on documentation improvements

02 Feb 2017, 13:44

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!
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
iPhilip
Posts: 802
Joined: 02 Oct 2013, 12:21

Re: Suggestions on documentation improvements

03 Feb 2017, 19:54

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.
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
glycoversi
Posts: 2
Joined: 25 Jan 2017, 17:15

Re: Suggestions on documentation improvements

13 Feb 2017, 19:41

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!
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

13 Feb 2017, 21:26

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

glycoversi
Posts: 2
Joined: 25 Jan 2017, 17:15

Re: Suggestions on documentation improvements

14 Feb 2017, 01:09

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.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

14 Feb 2017, 08:55

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

iPhilip
Posts: 802
Joined: 02 Oct 2013, 12:21

Re: Suggestions on documentation improvements

21 Feb 2017, 13:13

What does the `s escape sequence generate?
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

21 Feb 2017, 13:15

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...?

User avatar
joedf
Posts: 8940
Joined: 29 Sep 2013, 17:08
Location: Canada
Contact:

Re: Suggestions on documentation improvements

21 Feb 2017, 14:33

I think you might be right... It seems `s is only valid for that command.
Image Image Image Image Image
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]

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 6 guests