Suggestions on documentation improvements

Propose new features and changes
Guest

Re: Suggestions on documentation improvements

19 Jan 2015, 16:20

Documentation for SETTIMER:

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

thank you.
Peter2
Posts: 243
Joined: 21 Sep 2014, 14:38
Location: CH

"Iniread" - Documentation

25 Jan 2015, 14:28

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
Peter (AHK Beginner) / Win 7 x64, AHK Version v1.1.22.xx
lexikos
Posts: 6596
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Suggestions on documentation improvements

25 Jan 2015, 19:36

I have integrated some more of the suggestions in this thread for the next update.
Guest wrote: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.
Peter2 wrote: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
Posts: 243
Joined: 21 Sep 2014, 14:38
Location: CH

Re: Suggestions on documentation improvements

26 Jan 2015, 01:07

lexikos wrote:.....- 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.
Last edited by Peter2 on 30 Jan 2015, 14:26, edited 1 time in total.
Peter (AHK Beginner) / Win 7 x64, AHK Version v1.1.22.xx
kon
Posts: 1756
Joined: 29 Sep 2013, 17:11

Re: Suggestions on documentation improvements

30 Jan 2015, 12:57

FileSelectFolder wrote: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.
User avatar
jNizM
Posts: 2503
Joined: 30 Sep 2013, 01:33
GitHub: jNizM
Contact:

Re: Suggestions on documentation improvements

05 Feb 2015, 09:48

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?
[AHK] 1.1.30.03 x64 Unicode | [WIN] 10 Pro (Version 1903) x64 | [GitHub] Profile
Donations are appreciated if I could help you
User avatar
joedf
Posts: 7245
Joined: 29 Sep 2013, 17:08
Facebook: J0EDF
Google: +joedf
GitHub: joedf
Location: Canada
Contact:

Re: Suggestions on documentation improvements

05 Feb 2015, 19:42

Not really...
This one should work tho :
https://github.com/ahkscript/ASPDM/blob ... Anchor.ahk
Image Image Image Image Image
Windows 10 x64 Professional, Intel i5-8500 @ 4.00 GHz, 2x8GB DDR4 3143 MHz, NVIDIA GTX 1060 6GB | [About Me] | [ASPDM - StdLib Distribution]
[Populate the AHK MiniCity!] | [Qonsole - Quake-like console emulator] | [LibCon - Autohotkey Console Library] | [About the AHK Foundation]
peter_fargas
Posts: 4
Joined: 23 Feb 2015, 04:13

Re: Suggestions on documentation improvements

07 Mar 2015, 06:00

WinTitle: ahk_exe consumes the whole following string as the process path
peter_fargas
Posts: 4
Joined: 23 Feb 2015, 04:13

Re: Suggestions on documentation improvements

07 Mar 2015, 06:06

Command Line Parameters are not directly accessible by := syntax, resp. explicitly point towards using the = %i% syntax.
lexikos
Posts: 6596
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Suggestions on documentation improvements

07 Mar 2015, 07:24

peter_fargas wrote: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
Posts: 4
Joined: 23 Feb 2015, 04:13

Re: Suggestions on documentation improvements

07 Mar 2015, 12:58

lexikos wrote:
peter_fargas wrote: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?
lexikos wrote:
peter_fargas wrote: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
Posts: 6596
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Suggestions on documentation improvements

07 Mar 2015, 17:14

peter_fargas wrote: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).
GeekDude
Posts: 853
Joined: 02 Oct 2013, 22:13

ObjBindMethod missing from chm index

09 Mar 2015, 10:35

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.]
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

12 Mar 2015, 05:01

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
Posts: 6596
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Suggestions on documentation improvements

12 Mar 2015, 07:31

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.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

12 Mar 2015, 08:58

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
Posts: 6596
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Suggestions on documentation improvements

12 Mar 2015, 16:47

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."
trismarck wrote: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.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

13 Mar 2015, 04:53

Lexikos wrote: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.
Lexikos wrote:
trismarck wrote: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.
Lexikos wrote:
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().

Lexikos wrote:
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.
Lexikos wrote:
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).
Last edited by trismarck on 14 Mar 2015, 04:49, edited 1 time in total.
lexikos
Posts: 6596
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Suggestions on documentation improvements

13 Mar 2015, 17:13

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.
User avatar
trismarck
Posts: 506
Joined: 30 Sep 2013, 01:48
Location: Poland

Re: Suggestions on documentation improvements

14 Mar 2015, 06:37

Lexikos wrote: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).
Lexikos wrote:
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.
Lexikos wrote:
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.
Lexikos wrote:Insert and Remove will be deprecated in the next release (see here). I will attempt to clarify the documentation then.
Noted, thanks.

Return to “Wish List”

Who is online

Users browsing this forum: No registered users and 4 guests