[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

31 Jan 2019, 11:41

yes, i expect if one is interested in finding out what a function does to go through the entire page. its a 2 min read tops. RGB will have been covered, so it absolutely is duplication.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Format() and "literal text"

03 Feb 2019, 12:57

The format() command states
FormatStr

A format string composed of literal text and placeholders of the form {Index:Format}.
Nowhere does it say how the TEXT is used or what purpose it serves. Additionally, the "text" is not shown in the syntax, which, I think should be something like
<text>{Index:Format}<text>
User avatar
ineuw
Posts: 172
Joined: 11 Sep 2014, 14:12

Re: Suggestions on documentation improvements

08 Feb 2019, 14:53

Neither 'AutoReload' and 'Shift+Tab' are docmented. 'Shift+tab' is the reverse action of {Tab}
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

08 Feb 2019, 15:09

ineuw wrote:
08 Feb 2019, 14:53
Neither 'AutoReload' and 'Shift+Tab' are docmented. 'Shift+tab' is the reverse action of {Tab}
And what is AutoReload? Never heard of it.. so does my AHK version, it seems. (I am guessing the syntax here.)
And Shift+tab is a standard MS Windows shortcut - what is the connection to AHK? Are there special problems with remapping this which should be mentioned, like with Alt-Tab?

Please elaborate!
User avatar
ineuw
Posts: 172
Joined: 11 Sep 2014, 14:12

Re: Suggestions on documentation improvements

08 Feb 2019, 19:53

gregster wrote:
08 Feb 2019, 15:09
And what is AutoReload? Never heard of it.. so does my AHK version, it seems. (I am guessing the syntax here.)
And Shift+tab is a standard MS Windows shortcut - what is the connection to AHK? Are there special problems with remapping this which should be mentioned, like with Alt-Tab?
Please elaborate!
gregster, there are no problems. Everything is working fine. About Tab/Shift-Tab, both are standard Windows shortcuts, so if you list Tab in the documentation, perhaps Shift-tab should also be mentioned. I realized that there are a LOT of Windows shortcuts, so please ignore this.

ahk7 provided the code snipped of Reload as shown below. I wanted to read up about it.

Code: Select all

#SingleInstance force
#NoEnv
#Warn
#InstallKeybdHook
SetWorkingDir, D:\ahk-functions-library
SetTimer, AutoReload, 100000
#Include D:\ahk-functions-library\en-proof.ahk
~LWin::vk07
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

08 Feb 2019, 20:12

ineuw wrote:
08 Feb 2019, 19:53
ahk7 provided the code snipped of Reload as shown below. I wanted to read up about it.
Okay, I am just trying to understand what's going on with this AutoReload thing you mentioned, but this is clearly a user-defined function like we have uncounted numbers of in this forum.

While we have examples in the docs and in rare cases hints to useful user-defined functions outside of the docs, it is impossible to say if this would make sense to include without actually knowing the source code which is obviously #included here via another ahk-file that we don't see (this means, this snippet itself cannot be run without additional code that we don't know so far). For all we know, this could be simply a timer to a function or label with a Reload command in it.
I would recommend to ask ahk7 about it if you cannot locate the missing code you are interested in and if you think that this might be something niftier than a combination of SetTimer and Reload.

Edit: Looking at this thread, my impression is that en-proof.ahk is your own library file and that you came up yourself with this AutoReload-Timer - and not ahk7. :think:
User avatar
ineuw
Posts: 172
Joined: 11 Sep 2014, 14:12

Re: Suggestions on documentation improvements

08 Feb 2019, 22:40

ahk7 suggested using AutoReload in this thread https://www.autohotkey.com/boards/viewtopic.php?f=76&t=60167. The purpose of the AutoReload was to refresh the code because after about an hour the keyboard goes bananas in Firefox (and only in Firefox). So, I wanted to find and pinpoint the problem before contacting Firefox support. So, Windows may not be a problem but interference from Firefox shortcuts may be. AutoReload is an accepted action in AutoHotkey.
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

09 Feb 2019, 03:23

ineuw wrote:
08 Feb 2019, 22:40
ahk7 suggested using AutoReload in this thread https://www.autohotkey.com/boards/viewtopic.php?f=76&t=60167. The purpose of the AutoReload was to refresh the code because after about an hour the keyboard goes bananas in Firefox (and only in Firefox). So, I wanted to find and pinpoint the problem before contacting Firefox support. So, Windows may not be a problem but interference from Firefox shortcuts may be. AutoReload is an accepted action in AutoHotkey.

No, really, if you look at the code box in the first post (your post) of the thread, it is you that came up with it, as a label for SetTimer - ahk7 just slightly re-arranged your original code (I guess, it is possible that you got it yourself from a third party).

And no, AutoReload is really not a generally "accepted action in Autohotkey" - it is just an arbitrary label, a user-defined name - and we cannot know what it is doing in this case because we don't see what's in its actual subroutine. The only person who could know, is you. This label name could well have been "dafnakqwem" instead. Perhaps you should read the linked thread again - and about the use of labels, in general.

I suggest we continue this discussion in the Ask for Help forum, if this remains unclear.
(It is not my intention to annoy you, but I really have the impression that you got some general misconceptions about the use and syntax of AutoHotkey.)
User avatar
ineuw
Posts: 172
Joined: 11 Sep 2014, 14:12

Re: Suggestions on documentation improvements

09 Feb 2019, 13:33

gregster, you are absolutely right. Please accept my apologies about arguing, and my thanks for the time you invested in replying it to me.

Reload is a label for the loop, reloading the scripts at 10 second intervals. I found it as the last entry, and it was created awhile ago, possibly with instructions from ahk7. I will disable it for now because the reason why it was added is no longer valid. Thanks again .

Code: Select all

AutoReload:
Reload
Return
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

09 Feb 2019, 13:39

ineuw wrote:
09 Feb 2019, 13:33
gregster, you are absolutely right. Please accept my apologies about arguing, and my thanks for the time you invested in replying it to me.
No problem at all - I am happy that we could clear this up :thumbup:
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

10 Feb 2019, 18:57

4 issues.

GUICONTROLGET
- GuiControlGet: '(Blank)' subcommand. This can support the 'Text' (Static) control, but 'Text' is not listed.
- (I'm not sure of what the exact behaviour is, for GuiControlGet applied to a 'Text' control, because it isn't listed.)

[EDIT:]
- I would remove 'All control types are self-explanatory except the following:'.
- And state these explicitly as a group: Text/Button/Link/DateTime/MonthCal/GroupBox/Custom.
- Separating any where necessary e.g. Custom.
- (It's confusing, your eyes keep looking up and down for a control type that may or may not be there.)

IF OBJECT
- if: 'if var', where var is an object, always returns true. The 'if (expression)' page does not state this.
- Mentioned here:
Raw TRUE/FALSE test on an object - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=60963

- [EDIT:] A link could be added to this page (or the information copied):
Objects - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Objects.htm#Usage_Remarks

TERNARY OPERATOR
- Ternary operator: it could be stated explicitly that you must specify all 3 parts: '(a) ? (b) : (c)', i.e. '(a) ? (b)' does not work.
- This trips a lot of people up because the 4-liner 'if (a) LF (b) LF else LF (c)' is possible, however, the 2-liner 'if (a) LF (b)' is also possible.
Variables and Expressions - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Variables.htm#ternary
- It could simply be mentioned that 'ternary' means 3, so 3 arguments are required. Furthermore, if the terms unary/binary/ternary operator were mentioned/explained together, this might add more clarity. [EDIT:] E.g.:
Oracle Unary and Binary Operators - w3resource
https://www.w3resource.com/oracle/operators/index.php

DLLCALL AND POINTERS
- DllCall: clarification of what happens when you specify 'Ptr,0' and 'PtrP,0'/'IntP,0'/'UIntP,0' etc.
- Mentioned here:
DllCall: IntP/UIntP, Int64P/UInt64P, PtrP/UPtrP - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=39906&p=261091#p261091

- [EDIT:] 'Ptr,0', is the memory at address 0 write-protected, or is a crash possible?
- [EDIT:] 'PtrP,0', does this write to the variable called '0', does it write to and then discard a temporary variable? What happens?
Last edited by jeeswg on 27 Feb 2019, 11:48, edited 4 times in total.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

11 Feb 2019, 00:20

jeeswg wrote:
10 Feb 2019, 18:57
- GuiControlGet: '(Blank)' subcommand. This can support the 'Text' (Static) control, but 'Text' is not listed.
- (I'm not sure of what the exact behaviour is, for GuiControlGet applied to a 'Text' control, because it isn't listed.)
Leave SubCommand blank to retrieve the control's contents. All control types are self-explanatory except the following:
I guess it retrieve the control's content.
- if: 'if var', where var is an object, always returns true. The 'if (expression)' page does not state this.
- Mentioned here:
Raw TRUE/FALSE test on an object - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=60963
If the if-statement's expression evaluates to true (which is any result other than an empty string or the number 0),

- Ternary operator: it could be stated explicitly that you must specify all 3 ...
all operators require all operands and symbols.
- DllCall: clarification of what happens when you specify 'Ptr,0' and 'PtrP,0'/'IntP,0'/'UIntP,0' etc.
- Mentioned here:
DllCall: IntP/UIntP, Int64P/UInt64P, PtrP/UPtrP - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=39906&p=261091#p261091
it is clearly documented that the address of the argument is passed, I cannot see how it can be clarified.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

11 Feb 2019, 08:26

@Helgef: Thanks for your comments. But everything I said still stands, and I've expanded points in the spoiler.
Spoiler
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

what does the "=" operator do?

11 Feb 2019, 09:46

at https://autohotkey.com/docs/Variables.htm#Operators is shown the "=" operator.

What the = operator does IS NOT DEFINED. I think one of the MOST CONFUSING things about AHK is the difference between = and :=. I've been plagued with the issue for years.

It states the following:
Equal (=), case-sensitive-equal (==), and not-equal (<> or !=). The operators != and <> are identical in function. The == operator behaves identically to = except when either of the inputs is not a number, in which case == is always case sensitive and = is always case insensitive (the method of insensitivity depends on StringCaseSense). By contrast, <> and != obey StringCaseSense.

Note: A quoted literal string such as "55" is always considered non-numeric in this context.

Deprecated: The <> operator is not recommended for use in new scripts. Use the != operator instead.
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

11 Feb 2019, 11:38

@ joefiesta, you link to operators in expressions, the legacy assignment = isn't listed there because it cannot be be used in an expression. Legacy assignment is mentioned on the same page though, just a bit up. It has its own page here . A link to this page might be appropriate in connection to the other assignment operators, eg :=.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

IF and expressions

11 Feb 2019, 13:34

At the doc for "If (expression)" is stated
An if-statement that contains an expression is differentiated from a traditional-if such as If FoundColor <> Blue by making the character after the word "if" an open-parenthesis.
Sounds pretty straightforward. What follows "if " is not considered an expression unless preceded by a "(".

However, the doc at "variables and expressions" includes this:
Boolean values: When an expression is required to evaluate to true or false (such as an IF-statement), a blank or zero result is considered false and all other results are considered true. For example, the statement if ItemCount would be false only if ItemCount is blank or 0. Similarly, the expression if not ItemCount would yield the opposite result.
Here, the implication from "When an expression is required" is that in the example thereafter, "if ItemCount", ItemCount is an expression.

Is "If ItemCount" an expression? I can't figure that out because the doc seemingly contradicts itself. According to the first quote, it is NOT an expression because "ItemCount" is not preceded by a left parenthesis.
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

11 Feb 2019, 13:41

Well, the first parameter of If is always seen as a variable name - specifically without the use of %s. Hence, the first parameter must be an expression, otherwise we could not use the contents of this variable.
(For the second parameter of a comparison, it is a whole different story.)

Traditional If tells us about the first parameter:
Var
The variable name.
Edit:
I think if you start to talk about expressions in the traditional If docs, it would confuse people even more. In case of the use of operators, the traditional comparison is simply not an expression. But If ItemCount has no second parameter. That's why there are no problems with the question if expression or not - because the first parameter is clearly a variable name, like always with If, no matter what style. Also, parentheses don't hurt, they don't make a difference here: if (itemcount) is the same as if itemcount - simply because there is no comparison and no second parameter... and it is already an expression.
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

11 Feb 2019, 15:05

- GuiControlGet: It may be more subtle than that, I was exploring backporting AHK v2 GUIs, and something important was unclear.
Something was unclear, that means you should ask for help, so when it is not unclear anymore, you can make an actual suggestion. In general, this thread is mostly ask for help and no suggestions. If you ask a question, it is the wrong thread.
- I had thought that since an object returns an empty string,
Would you expect obj == "" to be true?
re. ?:. The problem is that there isn't a load time error, people omit : because they have seen others doing it, guessing it is valid, and they didn't read the docs. So changing the docs doesn't help.

Cheers.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

11 Feb 2019, 15:26

- The point about GuiControlGet + (Blank) + Text controls was to double-check its behaviour before updating the documentation. I can't remember if its behaviour was simple or complex. E.g. Submit/AltSubmit, and AHK v2 distinguishes between Text and Value.

- Many(/most?) people would expect obj == "" to be true, yes. I tested and it reported false, which arguably breaks the principle of least astonishment. I can think of arguments for both sides, I'd recommend starting a new thread if you want to pursue it further.
- (You do surprise me sometimes with what you think is 'normal', or what you think other people will expect as 'normal' e.g. force-local and 'can be expression' v. 'force an expression'. You're quite the lateral thinker. In fact, the fact that you asked the question implies that you anticipated some room for doubt in others.)
- Btw what about if {}? What's your expectation for that?
- And obj obj == "" gives true, while obj == "" gives false. There are parallels with IsObject(obj) and IsObject(obj obj),
- Btw in AHK Basic you did not have if obj or obj == "", so this behaviour needs to be defined somewhere, prominently, in the documentation.

- Yes, I think there should be a load-time error re. ternary operators in AHK v1. Changing the docs would help people who (a) read the docs, (b) are linked to the docs. I've added it to my Wish List 2.0. Cheers.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

12 Feb 2019, 03:54

Many(/most?) people would expect obj == "" to be true, yes.
I made a ridiculous example to help you realise that your comment,
- I had thought that since an object returns an empty string,
was nonsensical . I will try again, do you expect obj.key to be equivalent to "".key? And no, I do not think anyone would expect obj == "" to be true.
this behaviour needs to be defined somewhere, prominently, in the documentation.
It does, and It is :arrow: objects.

Cheers.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 7 guests