[Archived, Locked] Suggestions on documentation improvements

[Guest]

Documentation for SETTIMER:

1. The documentation should note that the numerical value of a PERIOD parameter must be an integer.

thank you.

[Peter2]

At the moment the help says:

Values longer than 65,535 characters are likely to yield inconsistent results.

Looking to different discussion threads this topic should be expanded to "Limits":
- for file
- for section
- for values
- different in characters and bytes (for Dummies).

Thanks

[lexikos]

I have integrated some more of the suggestions in this thread for the next update.

The documentation should note that the numerical value of a PERIOD parameter must be an integer.

That only applies if you specify it literally, as in SetTimer, Label, 1000.0. It's meaningless to use a decimal point here, because the timer period is not even accurate to-the-millisecond let alone to the fraction of a millisecond. At runtime, floating-point numbers are permitted but are truncated to integers.

Looking to different discussion threads this topic should be expanded to "Limits":
- for file

I'm not aware of any file limits.

- different in characters and bytes (for Dummies).

As far as I'm aware, the number of bytes is irrelevant. INI files are text (ANSI or UTF-16), and the limits are in characters.

[Peter2]

.....- for file
I'm not aware of any file limits....
.....As far as I'm aware, the number of bytes is irrelevant.....

I added it because sometimes it makes the information clearer when there is described "what is" and "what is not". This can avoid some questions like "But what's about ...".

Of course it is not a must, it is an option.

[kon]

Example

Code: Select all

FileSelectFolder, OutputVar, , 3
if OutputVar =
    MsgBox, You didn't select a folder.
else
    MsgBox, You selected folder "%OutputVar%".

CLSID Example:
FileSelectFolder, OutputVar, ::{20d04fe0-3aea-1069-a2d8-08002b30309d}  ; My Computer.

CLSID Example: should be commented.

[jNizM]

GuiSize

A script may use GuiSize to reposition and resize controls in response to the user's resizing of the window. This process can be made much easier by using #Include to load Titan's "Anchor" script.

Titan's "Anchor" script ==> 404 Not Found
github poly => Anchor

But... Does this script works fine with the latest AHK_L builds?

[joedf]

Not really...
This one should work tho :
https://github.com/ahkscript/ASPDM/blob ... Anchor.ahk

[peter_fargas]

WinTitle: ahk_exe consumes the whole following string as the process path

[peter_fargas]

Command Line Parameters are not directly accessible by := syntax, resp. explicitly point towards using the = %i% syntax.

[lexikos]

WinTitle: ahk_exe consumes the whole following string as the process path

No it doesn't. MsgBox % WinExist("ahk_exe notepad.exe ahk_class Notepad") works just fine, and the process name is obviously notepad.exe, not notepad.exe ahk_class Notepad. It also works with the full path.

Command Line Parameters are not directly accessible by := syntax, resp. explicitly point towards using the = %i% syntax.

My tired mind is having a hard time parsing that sentence.

Here the non-expression syntax is shown and a link for more details. Here the non-expression syntax is shown both before and after mentioning the limitation of expressions. The three examples following that use the non-expression syntax (and two of them also use expressions). As far as I can find, only Variable names mentions the expression limitation without showing the non-expression syntax, but it does provide a link that's hard to miss (incoming command line parameters) and that thoroughly covers the proper syntax to use.

[peter_fargas]

WinTitle: ahk_exe consumes the whole following string as the process path

No it doesn't. MsgBox % WinExist("ahk_exe notepad.exe ahk_class Notepad") works just fine, and the process name is obviously notepad.exe, not notepad.exe ahk_class Notepad. It also works with the full path.

Hm. I'm not getting happy with ahk_group containing a member ahk_exeE:\totalcmd851\TOTALCMD64.EXE ahk_classTTOTAL_CMD but the other way round yes ahk_classTTOTAL_CMD ahk_exeE:\totalcmd851\TOTALCMD64.EXE??? If full paths with spaces need special treatment is also not mentioned in the documentation - I tried enclosing in quotes but that did not work. I relied on http://www.autohotkey.com/board/topic/8 ... -priority/ and my judgement of unambiguity of the parser?

Command Line Parameters are not directly accessible by := syntax, resp. explicitly point towards using the = %i% syntax.

My tired mind is having a hard time parsing that sentence.

Here the non-expression syntax is shown and a link for more details. Here the non-expression syntax is shown both before and after mentioning the limitation of expressions. The three examples following that use the non-expression syntax (and two of them also use expressions). As far as I can find, only Variable names mentions the expression limitation without showing the non-expression syntax, but it does provide a link that's hard to miss (incoming command line parameters) and that thoroughly covers the proper syntax to use.

Well, although multiple usage scenarios are covered, the most basic need - getting the data into a variable which properly denotates that data by it's naming; is getting only implicit attention. It is one of the little places which forces fallback into the non-expression syntax - and the other places are rather loud about it, whereas here it's a single colon.

[lexikos]

I'm not getting happy with ahk_group

I am "getting happy" with ahk_group containing a member ahk_exeC:\Windows\System32\notepad.exe ahk_classNotepad (even though all of the examples have a space after ahk_exe).

[geek]

I couldn't find the documentation improvement thread, so I'm making a post here. Also, it might be beneficial to add an index entry for just "Bind()" that links here http://ahkscript.org/docs/objects/Func.htm#Bind

[Note by Lexikos: This post was moved from Bug Reports and the issue was fixed.]

[trismarck]

Perhaps it could be documented that just like ObjInsert() bypasses the special behaviour of the base key, ObjRemove() does this also - i.e. doing ObjRemove(obj, "base") won't remove/return the base of the object.

[lexikos]

The word "base" and the object's base aren't a key-value pair. Remove just removes key-value pairs.

The documentation for Insert is a bit backwards; __Set and "base" are only relevant for assignments. Insert just inserts a key-value pair.

[trismarck]

Yes. Thanks. So perhaps there could be symmetry between the description of ObjInsert() and ObjRemove() in the context of how they work with object's base (or actually, how they don't work).

//edit: after rethinking - there is a difference between setting the key to an empty value and removing the key. While the object's base can be set to an object / set to null (~ObjInsert() ), it can't be removed (~ObjRemove() ). Thus ObjInsert() and ObjRemove() aren't really 'symmetric' in terms of what they could potentially do to object's base. I was just thinking the other way around - if the object has a base, one could want to remove that object to get its value with ObjRemove(). But this could be done with two operations - returning the base and then setting the base to an empty string (which actually doesn't mean: remove the base...). So ObjRemove() can't remove object's base (and thus isn't subject to special behaviour of key 'base'), because the base of the object can't be removed in the first place, it can only be set to null.
//edit2: getting the value to be returned is part of the removal process, but if something can't be removed in the first place, there is no point in getting its value, as it won't be a successful removal anyway. Attempt to remove value, if successful, obtain removed value and return it, else, return w/o obtaining the value.
//edit3: but this is inconsistent, because in addition to object's base being impossible to be removed, the object's base can't also be inserted - it can only be set... So ObjInsert() isn't only about reassigning value of existing key, it can also be about inserting a brand new key. Its just that ObjInsert() can do two things: ObjInsert() and ObjAssign/Reassign() ... .
So now the conslusion is (I guess) this: if one can do four three things to a key of an object:

• insert
• assign
• remove

and only ObjInsert() is about assigning (vs ObjRemove() ), the note about object's base should only be in ObjInsert() (to be exact, the part of ObjInsert() that assigns, not inserts). A side-note could be that assigning is the same as reassigning (because after insertion of key, the key can only be reassigned), but then one could say that part of the insertion is assigning (initializing actually). Which would then make a difference between assigning and reassigning. But because the base can't be inserted, it can only be assigned, the note should be in the 'assign' part of ObjInsert(). Which is already the case.

[lexikos]

Insert, Remove, GetAddress, GetCapacity, HasKey and _NewEnum operate on key-value pairs. The object's base is not a key-value pair and can only be accessed via the [] or . operators. Like properties implemented with __Set and __Get, the behaviour of .base can be overridden by storing a key-value pair in the object. As indicated by the documentation, the object then has both its base object and a key-value pair with the key "base", but can access only one of them.
"For instance, Object.Insert("base","") causes Object.base to return an empty string instead of the real base object, but doesn't prevent other operations from triggering the object's meta-functions."

Thus ObjInsert() and ObjRemove() aren't really 'symmetric' in terms of what they could potentially do to object's base.

Yes they are. Neither one affects the base itself. Insert makes it inaccessible by creating a key-value pair. Remove makes it accessible by removing the key-value pair.

if the object has a base, one could want to remove that object to get its value with ObjRemove().

One should remove a key-value pair only to remove a key-value pair, not to get its value.

So ObjInsert() isn't only about reassigning value of existing key, it can also be about inserting a brand new key.

Obviously, inserting a value is the purpose of Insert. That it can be used to set an existing value is secondary, and only because I mistakenly figured it should do something useful if given a string instead of an integer.

But because the base can't be inserted, it can only be assigned, the note should be in the 'assign' part of ObjInsert().

What are you talking about? The base object cannot be assigned with Insert.

[trismarck]

Insert, Remove, GetAddress, GetCapacity, HasKey and _NewEnum operate on key-value pairs. The object's base is not a key-value pair and can only be accessed via the [] or . operators. Like properties implemented with __Set and __Get, the behaviour of .base can be overridden by storing a key-value pair in the object. As indicated by the documentation, the object then has both its base object and a key-value pair with the key "base", but can access only one of them.
"For instance, Object.Insert("base","") causes Object.base to return an empty string instead of the real base object, but doesn't prevent other operations from triggering the object's meta-functions."

Yes, all of this was part of the context of the post.

Thus ObjInsert() and ObjRemove() aren't really 'symmetric' in terms of what they could potentially do to object's base.

Yes they are. Neither one affects the base itself. Insert makes it inaccessible by creating a key-value pair. Remove makes it accessible by removing the key-value pair.

Ok, they are symmetric in the context of making object's base accessible. What I've meant by 'potentially' was that if they _could_ access object's base, ObjInsert() can really do two things: insert and [re]assign and ObjRemove() can only do one thing: remove. The word 'symmetric' really pertained not to object's base, but to how ObjInsert() and ObjRemove() work in general. ObjInsert() seems to have 'more functionality' if you will.
//edit: I guess the key word here was 'potentially' - if one would assume that ObjInsert() could work with object's base in exactly the same manner as with key 'base', _then_ ObjInsert() would still be asymmetric to ObjRemove(), in relation to _both_ the key 'base' and the object's base.

if the object has a base, one could want to remove that object to get its value with ObjRemove().

One should remove a key-value pair only to remove a key-value pair, not to get its value.

To clarify, that sentence was about: given the scenario in which an object has a base (vs the base key), the user (not knowing that ObjRemove() doesn't work with object's base, it just removes the key-value pair) (because it isn't documented that ObjRemove() _does_ bypass the special behaviour of key 'base'), would mistakenly use ObjRemove() in hope to get the base of the object (even if the object _doesn't_ have the key 'base'), and that would always fail. Thus the note in the documentation about bypassing behaviour of key 'base' should be part of ObjRemove(), as it is with ObjInsert() (or, at least that was my point then).
Another thing related to this sentence (in the context of ObjRemove() should only be used to remove an object, not to get its value) is this: in this thread, to retrieve the Property object, one has to use ObjRemove() (vs something like cx.fun.get) because the invocation of cx.fun will check if fun is a Property and if it is, instead of returning the Property object, getter of the Property will be called by the cx.fun invocation. So the point here was that in some cases, ObjRemove() _has to_ be used to get a value _first_, because 'just' getting the value through 'normal ways' is impossible.
Actually, I should have written DefaultBaseObject, not cx.
Another note would be that after the Property object was removed, one could want to insert the Property object back, with ObjInsert() (vs with an assignment) (~for 'symmetry' of operations).
//edit: to clarify, it is impossible to reassign the getter and the setter of the Property w/o removing the Property from the class object first. Thus i.e. if one would want to get the Function object of the getter, one can't just get the value, one has to first use ObjRemove().

So ObjInsert() isn't only about reassigning value of existing key, it can also be about inserting a brand new key.

Obviously, inserting a value is the purpose of Insert. That it can be used to set an existing value [...]

It's sort of what I've really meant by that ObjInsert() and ObjRemove() aren't symmetric - ObjRemove() can't 'unset' an existing value (and not remove the object) (vs just remove the object), whatever 'unsetting' would mean in this context (or perhaps, setting (vs 'unsetting') ). ObjInsert() inserts and reassigns, ObjRemove() removes only.

But because the base can't be inserted, it can only be assigned, the note should be in the 'assign' part of ObjInsert().

What are you talking about? The base object cannot be assigned with Insert.

The meaning of that sentence was this: the base of the object cannot be inserted _ever_ (including ObjInsert() ). But if one would assume that the object's base can either be set to an object or to null and at the same time ObjInsert() can _also_ either set a __key-value pair__ to an object or set it to an empty string (~vs insert/remove it, which is not possible (20150314- ~which is not possible for object's base) ), the note about bypassing the special behaviour of key 'base' should only be part of _ObjInsert()_, because it is _only_ ObjInsert() (vs ObjRemove() ) that is able to _set_ the key-value pair (and 'potentially', the object's base (but we know that in reality, it can't) ) (vs insert/remove it). Object's base isn't a field that can be inserted / removed in the first place; object's base can only be _set_ (to obj/null).

[lexikos]

I think that the users will be thankful that the documentation isn't as rambling as your posts.

So the point here was that in some cases, ObjRemove() _has to_ be used to get a value _first_, because 'just' getting the value through 'normal ways' is impossible.

No, it doesn't have to be used. There is no requirement that a script use a Property object directly. It's not even documented. And ObjRemove() isn't the only way to get it; you can use a for-loop for now.

The meaning of that sentence was this:

The meaning of mine was this: Insert inserts or replaces a key-value pair. Remove removes a key-value pair. They affect base in exactly equal and opposite ways: making it inaccessible or accessible. They have exactly the same indirect effect on properties declared in base classes.

Insert and Remove will be deprecated in the next release (see here). I will attempt to clarify the documentation then.

[trismarck]

I think that the users will be thankful that the documentation isn't as rambling as your posts.

To put this in perspective, I've once had the following situation. I was reading a thread on the forum and at some point I've encountered this post. After reading the beginning of it, I said to myself: "Wow, this is really hard to read.". And then I saw my name next to the post. (I have forgotten that I posted in that thread).

So the point here was that in some cases, ObjRemove() _has to_ be used to get a value _first_, because 'just' getting the value through 'normal ways' is impossible.

No, it doesn't have to be used. There is no requirement that a script use a Property object directly. It's not even documented. And ObjRemove() isn't the only way to get it; you can use a for-loop for now.

Didn't think about the for-loop, thanks.

The meaning of that sentence was this:

The meaning of mine was this: Insert inserts or replaces a key-value pair. Remove removes a key-value pair. They affect base in exactly equal and opposite ways: making it inaccessible or accessible. They have exactly the same indirect effect on properties declared in base classes.

To clarify, by "indirect effect" I understand making object's base either accessible or inaccessible, but never overwriting it / changing it [directly].
About "making the object's base inaccessible": at first thought, I've thought that if there is already a key in the object and Insert overwrites the value of that key, then Insert doesn't really 'make' the object's base inaccessible, because the object's base was inaccessible even before the Insert operation. But after rethinking, if one would look from the 'what is the state of object's base at the end of operation' point of view then both Insert and Remove _are_ equal - after doing Insert, object's base is inaccessible and after doing Remove, object's base is accessible.

So the confusion stemmed from the fact that I was looking at the word 'symmetry' from the point of view of 'atomic operations' of Insert/Remove and how those atomic operations of Insert/Remove should relate to key base and base of object, whereas I should be looking at the symmetry from the point of view: what is the 'end effect/end result' of doing Insert/Remove to the accessibility of object's base. Thanks.

Insert and Remove will be deprecated in the next release (see here). I will attempt to clarify the documentation then.

Noted, thanks.