If syntax in v2

Share your ideas as to how the documentation can be improved.
ThePeter
Posts: 49
Joined: 25 Oct 2022, 05:57

If syntax in v2

Post by ThePeter » 29 Nov 2022, 06:17

https://lexikos.github.io/v2/docs/commands/If.htm

As brackets are not required for the if expression in v2, it may be less misleading to remove the brackets from the documentation (and probably also from the examples). Old:

Code: Select all

If (Expression)
{
    Statements
}
New:

Code: Select all

If Expression {
    Statements
}

guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: If syntax in v2

Post by guest3456 » 29 Nov 2022, 09:14

expression-if is not required in v1, so does that mean we should change all the v1 documentation to use the old legacy if syntax?

obviously the answer is no

whether something is required or not is not sufficient justification to change the documentation. the examples in the docs should express a preference as a guide for readers. imo parenthesis should be kept if for no other reason than for consistency and compitability with v1


ThePeter
Posts: 49
Joined: 25 Oct 2022, 05:57

Re: If syntax in v2

Post by ThePeter » 29 Nov 2022, 10:21

If the syntax changes, it seems more or less reasonable to change the documentation as well...

guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: If syntax in v2

Post by guest3456 » 29 Nov 2022, 10:53

but the syntax hasn't changed.


lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: If syntax in v2

Post by lexikos » 29 Nov 2022, 21:30

It is not misleading to use parentheses in examples, or use any particular style for any other part of the syntax, despite there being other possible ways to write the code.

Parentheses are not required in v1 either, unless the syntax matches one of the legacy IF statements. if !var is a common one, but there are other patterns.

ThePeter
Posts: 49
Joined: 25 Oct 2022, 05:57

Re: If syntax in v2

Post by ThePeter » 30 Nov 2022, 00:01

Nevertheless, nothing in the documentation suggests that the parentheses are optional. I thought that it would be no big deal to clarify that. But this is not important enough to have lengthy discussions over, so do as you see fit

lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: If syntax in v2

Post by lexikos » 30 Nov 2022, 00:19

nothing in the documentation suggests that the parentheses are optional.
Really? Not even the examples on the IF page?

Code: Select all

if (x < y) {
    ; ...
}
if WinExist("Untitled - Notepad") {
    WinActivate
}
if IsDone {
    ; ...
} else {
    ; ...
}
There are actually various examples throughout the documentation that do not use parentheses.
The space after if is optional if the expression starts with an open-parenthesis, as in if(expression).
This suggests that the expression does not necessarily have to start with an open-parenthesis; otherwise, the space would always be optional.

Parentheses have never been a required part of the syntax, but something is often needed to disambiguate in v1. It is not needed in v2 and could be removed from the syntax block at the top of the IF page. There is no need to change the examples, which already show that using parentheses is valid but not mandatory.

ThePeter
Posts: 49
Joined: 25 Oct 2022, 05:57

Re: If syntax in v2

Post by ThePeter » 30 Nov 2022, 00:32

It is not needed in v2 and could be removed from the syntax block at the top of the IF page.
This is exactly my original suggestion.

lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: If syntax in v2

Post by lexikos » 30 Nov 2022, 19:20

It is approximately your original suggestion.

Post Reply

Return to “Suggestions on Documentation Improvements”