[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

15 Sep 2014, 17:48

lexikos wrote:guest3456: It's not an expression. It's the EnvAdd command.
Var += Value [, TimeUnits]
...
%Var%: For backward compatibility, command parameters that are documented as "can be an expression" treat an isolated name in percent signs (e.g. %Var%, but not Array%i%) as though the percent signs are absent.
Ahh, gotcha.

I just checked and in v2, it seems that it is an expression (and double-deref) as I would expect

just me
Posts: 9424
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Suggestions on documentation improvements

16 Oct 2014, 04:22

ControlGetFocus

The example for GetGUIThreadInfo() in the Remarks section isn't 64-bit compatible. It should be changed like:

Code: Select all

; This script retrieves the ahk_id (HWND) of the active window's focused control.
GuiThreadInfoSize := 8 + (A_PtrSize * 6) + 16
VarSetCapacity(GuiThreadInfo, GuiThreadInfoSize)
NumPut(GuiThreadInfoSize, GuiThreadInfo, 0)
if not DllCall("GetGUIThreadInfo", "UInt", 0, "Ptr", &GuiThreadInfo)
{
    MsgBox GetGUIThreadInfo() indicated a failure.
    return
}
FocusedHWND := NumGet(GuiThreadInfo, 8 + A_PtrSize)  ; Retrieve the hwndFocus field from the struct.
MsgBox % "The focused control's ahk_id (HWND) is " . FocusedHWND
; This ID can be used all control commands.  For example:
; ControlGetText, OutputVar,, ahk_id %FocusedHWND%
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

29 Oct 2014, 17:19

Perhaps the example in the quote could be added to GuiControl as well.
GuiControlGet ([url=http://ahkscript.org/docs/commands/GuiControlGet.htm]link[/url]) wrote:As with any other ControlID, Sub-command must also include the name or number of the GUI if it is not the default window. For example, GuiControlGet Value, 2:, %Hwnd%.
Background.

//edit: it's already there, just at a different place...
GuiControl ([url=http://ahkscript.org/docs/commands/GuiControl.htm]link[/url]) wrote:To operate upon a window other than the default (see below), include its name or number followed by a colon in front of the sub-command as in these examples:

GuiControl, MyGui:Show, MyButton
GuiControl, MyGui:, MyListBox, Item1|Item2
User avatar
Almost_there
Posts: 404
Joined: 30 Sep 2014, 10:32

Re: Suggestions on documentation improvements

21 Dec 2014, 07:13

In documentation for IfInString / IfNotInString it shoult mention that it the Haystack cannot be a variable.

I had this problem that IfInString always acted as if the SearchString wasn't found even if it obviously should be found. Then I found this thread explaining why - and afaik that's the only place on the internet wher this info exist.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

21 Dec 2014, 21:45

You just need to use the right syntax: %HaystackVar% or HaystackString.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

23 Dec 2014, 23:33

Almost_there wrote:In documentation for IfInString / IfNotInString it shoult mention that it the Haystack cannot be a variable.

I had this problem that IfInString always acted as if the SearchString wasn't found even if it obviously should be found.
no idea what you're talking about

the example code in the docs works fine, and it passes variables for BOTH params

Code: Select all

Haystack := "abcdefghijklmnopqrs"
Needle := "abc"

IfInString, Haystack, %Needle%
    MsgBox, The string was found.
else
    MsgBox, not found
Almost_there wrote: Then I found this thread explaining why - and afaik that's the only place on the internet wher this info exist.
That post is talking about the 2nd argument, which is the needle, not the haystack, but I have no idea what he's talking about because as i said the code works fine

just me
Posts: 9424
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Suggestions on documentation improvements

07 Jan 2015, 05:18

FileOpen(Filename, Flags [, Encoding])
Flags
Access modes (mutually-exclusive)
h
Indicates that Filename is a file handle to wrap in an object. Sharing mode flags are ignored. The file handle is not closed automatically when the file object is destroyed and calling Close has no effect. Note that Seek, Tell and Length should not be used if Filename is a handle to a nonseeking device such as a pipe or a communications device.
I should be mentioned that the parameter Encoding is ignored, too.
just me
Posts: 9424
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Suggestions on documentation improvements

08 Jan 2015, 02:49

You're right, my bad. It just does'nt read/write the BOM.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

08 Jan 2015, 02:58

Ironically, if and when FileOpen reads a BOM, it ignores the Encoding parameter.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

14 Jan 2015, 06:43

Classes wrote:In addition to the hidden parameter this, method definitions can use the pseudo-keyword base to invoke the base class of the class which contains the method definition. For example, base.Method() in the method above would be equivalent to BaseClassName.Method.(this). Note that this differs from this.base.base.Method() in two other ways:
  • It always invokes the base of the current class, even if this is derived from a sub-class of the current class.
  • It passes this automatically, not this.base.base.
  • It never causes a meta-function to be called.
Source: http://ahkscript.org/docs/Objects.htm#Custom_Classes
I find the two bolded parts inexplicit - if BaseClassName.Method.(this) is equivalent to base.Method(), why does base.Method() never trigger meta-functions. Perhaps they could be rephrased.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

14 Jan 2015, 19:11

N.B. "in the method above". No meta-functions exist.

It's very clearly shown that the two don't always function identically by the text following that which describes how they differ.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

15 Jan 2015, 03:23

Ok, so the mistake I've made was to interpret the line:
Methods wrote:For example, base.Method() in the method above would be equivalent to BaseClassName.Method.(this).
in the context where the base of BaseClassName could have meta-functions. But the quote really pertains only to the example code at the beginning of the Classes section. Which is logical - in addition to the base of BaseClassName having meta-functions, one could assume other things about the base of BaseClassName, i.e. that it has a functor as a meta-function or has 10 more bases or has the key Method etc. Instead of assuming and describing all of the exceptions, there is just an example in the documentation and the quote pertains only to that example.
OTOH the next sentence:
Methods wrote:Note that this differs from this.base.base.Method() in two other ways:
pertains to base.Method in general.
While rereading the documentation this time, I've also spotted this:
Methods wrote:Note that this differs from this.base.base.Method() in _two_ other ways: [three bullet points listed]
Okay, thank you for pointing this out Lexikos, that explains it.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

15 Jan 2015, 04:33

I think your problem is that you are interpreting certain words according to exact meanings, but the wrong ones. I have this problem too, sometimes.

This thread is supposed to be about suggestions for improvement, not for help interpreting the current documentation. You didn't appear to post a suggestion. (Neither did I, so perhaps we're both in the wrong forum.) ;)

In any case, I can see there's a problem with that paragraph. I think it suffers from having been edited too many times. One of the three items was probably moved from the paragraph above it, hence "two other ways", not "two ways".
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

15 Jan 2015, 06:24

Sorry trismarck - That the example does not include meta-functions is completely beside the point. I had a number of objections to your comment, and picked one almost at random because I couldn't spend long was being hasty. (I've now spent several hours on this subject, which is several hours more than I wanted to.) The fact is that "would be equivalent to" does not mean "is identical to in every way" and was not intended to mean that.

The comparison between base.Method() and this.base.base.Method() is mostly an unneeded distraction, trying to explain why the latter should not be used. What should be written is just how base.Method() actually behaves.

How is this?
Inside a method, the pseudo-keyword base can be used to access the super-class versions of methods or properties which are overridden in a derived class. For example, base.Method() in the class defined above would call the version of Method which is defined by BaseClassName. Meta-functions are not called; otherwise, base.Method() behaves like BaseClassName.Method.(this). That is,
  • base.Method() always invokes the base of the class where the current method was defined, even if this is derived from a sub-class of that class or some other class entirely.
  • base.Method() implicitly passes this as the first (hidden) parameter.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

15 Jan 2015, 14:13

I like it very much. I especially like the sentence about the intended use of base. When testing, I wondered in what scenarios base could have been used and why was it so that base does not call meta-functions (when reading the documentation for the first time, I've wrongly assumed that base.Method just works _exactly_ like BaseClassName.Method so I've just thought that base was added for convenience, so one doesn't have to write the name of the super-class in the method 'by hand').
After rethinking and searching the forums, it turned out to me that base was actually designed to call overridden methods, esp. in a scenario in which the first method in the inheritance chain was already found through the inheritance algorithm - because the method was found, no other versions of that method in super-classes are called through the inheritance algorithm (an exceptions is meta-functions - if meta-function doesn't handle the operation, meta-function of base class is called anyway, w/o the need of base). But, if there exists a need to call versions of Method from super-classes too, base can be used. Meta-functions are not called, because the assumption is that we've already found the method we were looking for during the traversal of the inheritance chain (I guess).
Lexikos wrote:I think your problem is that you are interpreting certain words according to exact meanings, but the wrong ones. I have this problem too, sometimes.
Yes, I seem to have this problem. I also wonder what's causing it; hyhyhyh.

//edit: actually, now that I think of it:
  • this.base.base.Method() was useful for comparison purposes
  • I'm not sure if base.Method() behaves exactly like BaseClassName.Method.(this) if Method contains something other than a function reference (or name?), like a functor instance object
. Would have to test that to post a response...
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

16 Jan 2015, 05:09

Ok, here are some notes after sleeping with this:
Inside a method, the pseudo-keyword base can be used to access the super-class versions of methods or properties which are overridden in a derived class.
Perhaps the word 'invoke' would be better - 'invoke' was used before in the documentation.
For example, base.Method() in the class defined above would call the version of Method which is defined by BaseClassName.
So the assumption here is that BCN has the method defined. If the assumption should not be made, perhaps something like this could be added: "possibly defined by BCN or one of its super-classes".
Meta-functions are not called; otherwise, base.Method() behaves like BaseClassName.Method.(this).
Here, I'd say there could be two choices - either leave the revised version of the documentation as it is (and not compare base.Method to this.base.base.Method() at all - it seems hard to come up with a 'clear' description of BCN.Method.(this) / this.base.base.Method() / base.Method() in just one sentence):
That is,
  • base.Method() always invokes the base of the class where the current method was defined, even if this is derived from a sub-class of that class or some other class entirely.
  • base.Method() implicitly passes this as the first (hidden) parameter.
or perhaps create a table comparing all three, in terms of:
  • calls meta-functions
  • always invokes base of _current_ class
  • uses this as first parameter.
That would mean the duplication of information about meta-functions in trade of the table depicting everything separately. But perhaps conciseness is more valued and this.base.base.Method() shouldn't be mentioned at all (or just mentioned that it's there, somewhere at the end).
Meta-functions are not called; otherwise, base.Method() behaves like BaseClassName.Method.(this).
Lexikos wrote:The comparison between base.Method() and this.base.base.Method() is mostly an unneeded distraction, trying to explain why the latter should not be used. What should be written is just how base.Method() actually behaves.
Yes, I agree that base.Method() should be compared mainly to BaseClassName.Method.(this) (vs to this.base.base.Method()). The syntax of BaseClassName.Method.(this) denotes clearly, that it is the __Get (vs __Call) operation. The same is true for Properties: base.Method() does call the _Get_ half-property (~there is no Call property).

After testing if base.Method() behaves exactly like BCN.Method.(this) with:
  • function references
  • function names
  • functors
  • Properties,
there seems to be a difference with functors: (in params passed to __Call of the functor)

Code: Select all

class Properties {
	__Call(aP*) {
		msgbox, % "param count: " (aP.MaxIndex() = "" ? 0 : ap.MaxIndex())
		. "`n" (IsObject(aP[1]) ? "<Object>" : "|" aP "|")
		. "`n" (IsObject(aP[2]) ? "<Object>" : "|" aP "|")
		. "`n" (IsObject(aP[3]) ? "<Object>" : "|" aP "|")
	}
}
class dx {
	static Method := {base: Properties}
}
class cx extends dx {
	Method() {
		msgbox cx_method
		;base.Method() ; switch those
			; 1 - Object
		dx.Method.(this)
			; 1 - ""
			; 2 - Object()
	}
}
x := new cx()
x.Method()
I also like the idea of splitting this discussion into a separate topic, i.e.: "base pseudo-keyword inside of method - documentation" or sth similar.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

16 Jan 2015, 06:09

I'm satisfied with the way it is now. I see no need for further discussion or revision.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

16 Jan 2015, 06:57

Ok, thanks.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 11 guests