[Archived, Locked] Suggestions on documentation improvements

[swagfag]

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]

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>

[ineuw]

Neither 'AutoReload' and 'Shift+Tab' are docmented. 'Shift+tab' is the reverse action of {Tab}

[gregster]

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!

[ineuw]

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

[gregster]

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.

[ineuw]

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.

[gregster]

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

[ineuw]

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

[gregster]

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

[jeeswg]

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?

[Helgef]

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

[jeeswg]

@Helgef: Thanks for your comments. But everything I said still stands, and I've expanded points in the spoiler.

Spoiler

- GuiControlGet: It may be more subtle than that, I was exploring backporting AHK v2 GUIs, and something important was unclear.

- if: I, jballi and others with a good knowledge of AHK have been left confused by this.
- I had thought that since an object returns an empty string, perhaps you should expect 'if obj' to return false (but it returns true).

- Ternary operator: same principle as for 'if'. If multiple users with a good knowledge of AHK have been left confused by something, you should mention it explicitly.
- A key problem is that AHK v1 inadvertently allows you to use a 'binary ternary operator' in some circumstances. lexikos even mentioned it here because so many had been confused by it:
v2-changes
https://autohotkey.com/v2/v2-changes.htm

A load-time error is raised for more syntax errors than in v1, such as:
...
•Ternary operator with less than three operands.

- There's a description of the 'incomplete ternary operator' problem, here:
an Array of "ClipboardAll" contents - Page 2 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=60712&p=258110#p258110

- DllCall: For 'PtrP,0'/'IntP,0'/'UIntP,0' etc, it is not clear what the address of '0' is (what happens when you specify a number instead of a variable name). For Ptr, it is not clear if AHK is protecting address 0 from being written to, i.e. if you can depend on 'Ptr,0' always being safe. If it is safe, this facilitates writing code where you don't care about the pointer.

- All of these problems have wasted hours of my coding time, and that of others, they were carefully selected and explained.
- We're fortunate in the past, that you've frequently spotted things in the documentation that other people haven't. You have a rare talent for interpretation, exemplified by your many contributions to the Code Puzzle Thread.
- Unfortunately, I've found before that you're too generous with any shortcomings of the documentation. It's mostly good but there have been some parts that almost nobody could understand, that could have been written by The Riddler. Some parts I've tried to 'fix' by writing tutorials.

[joefiesta]

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]

@ 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]

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]

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]

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

[jeeswg]

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

[Helgef]

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

Cheers.