[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

12 Feb 2019, 05:20

"https://www.autohotkey.com/docs/Functions.htm#VariadicCall
this here says
The array of parameters may contain named items when calling a user-defined function; in any other case, named items are not supported.
but the following will work as well:

Code: Select all

FuncObj := Func("someuserdefinedfunction")
%FuncObj%({first: "hello", second: "world"}*)
also array of parameters may contain named items, "array" implies [] which doesnt have "named items"
change to associative array or object

on a side note, maybe call * something other than "variadic function call". what is a variadic function call?

Code: Select all

variadic(params*) {
}

variadic(123, "abc") ; im doing a 'variadic function call'

normal(a, b) {
}

normal([123, "abc"]*) ; im doing a 'variadic function call'
"array expansion operator" would be more selfexplanatory
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

12 Feb 2019, 08:05

No thats not how it works. Variadic function call and variadic function definition are 2 different things.
It is not an operator nor is a variadic function definition a variadic function call.

Code: Select all

variadic(params*) { ;im doing a variadic function definition
}

variadic(123, "abc") ; im doing a function call

normal(a, b) { ;im doing a function definition
}

normal([123, "abc"]*) ; im doing a variadic function call
operator would imply that it is available for general use in expressions - which it isn't.
It's only available once per function and only at the end of the function making it a special type of function call/definition rather than an operator.
Recommends AHK Studio
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

12 Feb 2019, 09:20

no, i know how it works, the point is it leads to semantic ambiguity. variadic(123, "abc") happens to be defined as a variadic function and ure calling it, hence ure doing a variadic function call
and on the operator thing, fine, u can call it "the trailing argument expansion operator". that way its clear its for use with functions only. and it is an operator. it operates on the last function argument
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

12 Feb 2019, 09:35

happens to be defined as a variadic function and ure calling it, hence ure doing a variadic function call
No it's not? The proper term would be calling a function that uses variadic parameters.
You wouldn't say optional function call when one of the parameters is optional or? the variadic definition is part of the definition and not part of the call therefore it's not a variadic function call.
Recommends AHK Studio
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

12 Feb 2019, 10:47

@helgef:

re: what does the "=" operator do?

You missed my point. I probably should not have introduced := into the discussion. My point is very, very simple. What does the "=" operator do?

The doc, at https://www.autohotkey.com/docs/Variables.htm#Operators , states:
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.
Nowhere in the above does it say what the = operator actually does!
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

12 Feb 2019, 11:11

- @joefiesta: Yes, the entry for = doesn't mention for example that it handles numeric comparison differently from string comparison. Also it doesn't mention that = can be used for assignment in AHK v1. (Strictly speaking though, when you use = for assignment, that is not an operator, it is part of a 'var = value' line, and you can't use = for assignment in expressions, you can use := however.)

- @Helgef: I read what you say sometimes as effectively almost this: 'the current behaviour is the most logical because it's the current behaviour'.
- The point about obj == "" is that you could say that both resolve to blank strings, so equality, or, if you compare an object to a string, what should the rule be: compare their string values, or compare their addresses perhaps. Because of the possibility of ambiguity, I would do some tests.
- When you do var := "" obj or if obj perhaps it should do: var := "" ObjToString(obj) or if ObjToString(obj).
- Note: it's easy to compare addresses with the & operator, so this suggests against comparing the addresses of objects as the default behaviour: &obj1 == &obj2.
- Perhaps if var should work like this IsEmpty function.

Code: Select all

q:: ;test - compare objects
MsgBox, % IsEmpty(0) ;0
MsgBox, % IsEmpty("") ;0
MsgBox, % IsEmpty([]) ;0
MsgBox, % IsEmpty(["a"]) ;1
MsgBox
MsgBox, % !!0 ;0
MsgBox, % !!"" ;0
MsgBox, % !![] ;1
MsgBox, % !!["a"] ;1
return

IsEmpty(var)
{
	if IsObject(var) && !ObjCount(var)
		return 0
	else
		return !!var
}
- Ultimately these decisions are difficult, and I'm OK with the current behaviour.

- The information here about equality operators is great, thanks for sharing. I would recommend it be linked to or copied to the 'if (expression)' page.
Objects - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Objects.htm#Usage_Remarks
- There is *so much* content on objects, that any important content that overlaps with other commands/functions/control flow statements etc should be linked to/mentioned in those pages also.
- The fact that this content was not mentioned in the 'if (expression)' page reaffirms what I said about AHK Basic, object functionality has been added for around 10 years, but the information is yet to be more fully integrated into the documentation. Cheers.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

12 Feb 2019, 11:50

Where does the variable Obj containing an object resolve to an empty string?
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

12 Feb 2019, 12:00

@nnnik:

Code: Select all

q:: ;object resolves to blank string
obj := {}
MsgBox, % obj ;(blank)
MsgBox, % StrLen(obj) ;0
var := obj
MsgBox, % StrLen(var) ;0
var := "" obj
MsgBox, % StrLen(var) ;0
return
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, 12:37

@ joefiesta, there was no misunderstanding.
@ jeeswg,
'the current behaviour is the most logical because it's the current behaviour'.
I didn't comment on the logic of the behaviour, I commented on the lack of logic in your comment,
- I had thought that since an object returns an empty string,
An object doesn't return anything. The current behaviour is logic though. The meaning var == "" is one of the first things one will learn when learning ahk, it is how you check if a variable is empty. If var refers to an object, it isn't empty. Forcing additional checks such as isobject(var) isn't helpful.
perhaps it should do: var := "" ObjToString(obj)
Perhaps it should, and perhaps it will,
object - remarks wrote:Do not rely on this behaviour as it may change.

- The information here about equality operators is great, thanks for sharing. I would recommend it be linked to or copied to the 'if (expression)' page.
You see, now that you have received help you are ready to make an actual suggestions, you are welcome.

Cheers.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

12 Feb 2019, 14:07

Code: Select all

q:: ;object resolves to blank string
obj := {}
MsgBox, % obj ;(blank)
MsgBox, % StrLen(obj) ;0
var := obj
MsgBox, % StrLen(var) ;0
var := "" obj
MsgBox, % StrLen(var) ;0
return
The behavior of StrLen with objects is undocumented and undefined. StrLen is clearly only meant for strings.
Numbers will get turned into strings for it. I think lexikos added the same behavior for objects since only a string makes sense here.
All types will turn into strings - StrLen causes a conversion.
The behavior of MsgBox is similar it turns everything into a string only works with a string - it makes sense to turn everything into a string.
Appending a string will force the object to be turned into a string and therefore result in a string.

Does == turn an object into a string? Does it make sense to say that 2 things are equal when one is an object full of data and all kinds fo things while the other is an empty string and the equivalent of nothing in a very restrictive comparison?
According to you yes it does which raises a few questions on my side.
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

12 Feb 2019, 17:21

- @Helgef: I provided 4 simple recommendations here:
Suggestions on documentation improvements - Page 26 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=13&t=1434&p=262959#p262959
- I tried to avoid an extended discussion in this thread, by providing links to existing discussions in that post.
- You raised some points, and I addressed them.
- You mentioned a useful link, and I thanked you for it.
- In my view, any other way of considering my comments is over-analysing things.

- Re. 'IsEmpty', if var reports false for a 'null' string (empty), and false for a 'null' number (0), users *might* expect it to report false for a 'null' object (no keys).
- There are multiple possible sensible expectations, and often there is no 'obvious' expectation, hence the benefits of the documentation.
- We don't, at present, have many functions that return objects, having 'if emptyobj' return false might be more useful than the current behaviour in such circumstances. Anyhow, we could keep things as they are and introduce an IsEmpty function.

- @nnnik:
Does == turn an object into a string? Does it make sense to say that 2 things are equal when one is an object full of data and all kinds fo things while the other is a very restrictive comparison?
According to you yes it does which raises a few questions on my side.
- Since I already said this:
if you compare an object to a string, what should the rule be: compare their string values, or compare their addresses perhaps
- I question what you posted, and why you posted it.
- It's been said of you before that you like to deliberately mischaracterise people and hurl ridiculous insults at people.
- I'm bored of it, you are the only user who regularly engages in behaviour like this, I would strongly discourage you from behaving like this in future. It's 2019 now. Give people the benefit of the doubt whenever you can, and try to show the proper respect whenever you can.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

12 Feb 2019, 21:54

Im just asking myself how you get the idea of why an object and a string could be the same thing in a comparison.
How did you reach this conclusion? What train of thought led there? There is no possible way to compare an object to a string because they are completely unrelated datatypes.

In my eyes this is dead weight that we carry around from AHK basic - all types had a string representation. Because Integers do and floats do and thats all the types we have.
And someone thought it might be a smart way to handle the problem of datatypes, by turning all datatypes into strings - everything is a string you don't need special datatypes anymore.
It's a smart solution to easily create a dynamic type system when these are the only types.
So you suddenly add a COM object that represents an instance of excel running in the background - but well the script doesn't know that - it pretty much only sees COM Object.
What kind of string do you want to turn it into? A random number like the adress? Something unique for each object.
lexikos just chose the most nondescriptant value possible in order to make things work - an empty string.
And you add more Object types and all of them need a string representation due to some very old restrictions.
And you all give them the same string representation because "I will do that later" or something along the lines (Google technical debt).

Now you come along and act as if objects turning into strings is the most logical thing in the world and that when comparing them the fact that they can turn into strings is more important than the fact that they are not strings yet but objects.
When comparing 2 objects you check if it is the same object - that is done via address in AHK. That is the most logical behavior. It's the most commonly used behavior in all other languages I know and have heard of.
I have never heard of anything like that being used in any other language. What you suggested is so far removed from anything I would consider common sense that I cannot even describe it.
And you defend it like it's the most reasonable thing in the world - instead of just accepting that you are wrong.
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

12 Feb 2019, 22:12

- When you compare two items of different types, either you get an error, or you determine *some* measure of comparison, a metric. What sensible comparison rules could you come up with? I mentioned compare as strings or compare addresses as 2 ideas.

- I've mentioned some ideas here:
ideas for if-statements - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=61991

- When I see a comparison/if-statement in *AutoHotkey* that I haven't considered before, I consider what the likely result will be based on past experiences of *AutoHotkey*.

- There's a recurring problem that you attack people in a personal way when you think that they're wrong. If someone was wrong about something, in a public forum, it really helps to attack the proposition rather than the person, and to do so as gently as possible.
- Also, it's better just to get your opinion out there, it's a discussion, not a formal debate, it's not about victory and defeat.
- Based on my reply here, perhaps it was you that was 'wrong', in which case, what should your response be?
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

13 Feb 2019, 03:47

I provided 4 simple recommendations here:
1) GuiControl, no recommendation, ask for help.
2) If var, no recommendation, false statement.
3) ?:, an actual suggestion, although not very precise. It later turned out you wanted a load time error, so it should be in the wish list instead.
4) DllCall, no recommendation, ask for help.
- I tried to avoid an extended discussion in this thread, by providing links to existing discussions in that post.
Links where not related to improvement of documentation. In fact, all links showed that the information was already provided in the documentation. To avoid extended discussions, make suggestions on documentation improvement (preferably one per post), based on understanding, if you lack it, ask for help first. I don't know what this means - clarify it!, isn't constructive and doesn't belong in this thread, and hence, such posts and any following discussion should be moved out of this thread, imo.

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

Re: Suggestions on documentation improvements

13 Feb 2019, 08:12

- For GuiControlGet, I said that the (Blank) description could be improved, e.g. does the CR+LF behaviour for Edit controls apply to 'Text' (Static) controls.
- It might be better to cover any missing control types explicitly, including Custom.

- For 'if obj' and 'a ? b : c' with no ': c', when long-time users like jballi and swagfag have recently expressed surprise or uncertainty about something important, (and I remember feeling likewise,) that's a very good argument that the documentation for 'if' and operators should be improved.
- (When I checked the documentation I was surprised how scantly these were covered.)
- (A load-time error would only effect newer scripts, so additional documentation would still be beneficial.)
- (Btw you might not think it's AutoHotkey's place to do this, but, on reflection, I would consider explaining unary/binary/ternary operators on the page. [EDIT:] Or at least state that 'ter' implies 3.)

- The point is that for 'Ptr,0' and for 'PtrP,0', the documentation does not make it clear what the user's expectations should be.
- Can 'Ptr,0' ever crash a script, are bytes 0-7 safely read-only? What does 'PtrP,x' do, where x is a number, not a variable name.

- In sum:
- 'Ptr,0'/'PtrP,0' is fundamentally important information.
- if/ternary are *classic* documentation improvements, because people keep being tripped up by the lack of key information in the obvious places.
- GuiControlGet is commonly used and key to GUIs.
isn't constructive and doesn't belong in this thread
- That's how I felt about your first response, and about your subsequent responses. The 4 points are classic documentation improvement fare, and you have not made a good case for their not being included.

Bonus content:
Spoiler
Last edited by jeeswg on 15 Feb 2019, 16:05, edited 1 time 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
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Function calls, parameters and expressions

14 Feb 2019, 11:23

Doc, at https://autohotkey.com/docs/Functions.htm#intro, states
Since a function call is an expression, any variable names in its parameter list should not be enclosed in percent signs.
this is not precise. The "function call" is not an expression. If it were, the following would work:

Code: Select all

in := "strlen"
a := in("asdf")
msgbox % a
exitapp
The doc should read: The PARAMETERS in a function call are expressions.
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

14 Feb 2019, 11:32

A function call is an expression (they would be pointless, if they weren't), but obviously the function name is not a variable (but nobody says that)... yes, variables and functions are not the same and do not have the same syntax.
A_AhkUser
Posts: 1147
Joined: 06 Mar 2017, 16:18
Location: France
Contact:

Re: Function calls, parameters and expressions

14 Feb 2019, 16:51

joefiesta wrote:
14 Feb 2019, 11:23
The "function call" is not an expression. If it were, the following would work:[...]
Documentation @Operators in Expressions - Expression Operators wrote:The following types of sub-expressions override precedence/order of evaluation:
[...]
Function call. The function name must be immediately followed by an open-parentheses, without any spaces or tabs in between.
source: Operators in Expressions (my italic)
my scripts
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

14 Feb 2019, 17:38

you guys don't get the point. My ONLY point is the semantics of the statement "Since a function call is an expression" The function call is NOT an expression. The Parameters are expressions, but not the call itself.
A_AhkUser
Posts: 1147
Joined: 06 Mar 2017, 16:18
Location: France
Contact:

Re: Suggestions on documentation improvements

14 Feb 2019, 18:24

joefiesta wrote:
14 Feb 2019, 17:38
The function call is NOT an expression. The Parameters are expressions, but not the call itself.

Code: Select all

GUI, +LastFound
if (WinExist()) {
	MsgBox % var := WinExist()
}
my scripts

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 8 guests