Optional parameter syntax can be ambiguous

[RussF]

I just ran into a situation that really had me stumped for some time regarding the syntax surrounding optional parameters. Take for example Format:

String := Format(FormatStr [, Values...])

I've come to expect that anything within square brackets is optional and when followed by an ellipsis, is repeatable, however, the actual square brackets are not used within the code itself.

This is even documented in Concepts->Functions:

ControlSend Keys [, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
Square brackets signify that the enclosed parameters are optional (the brackets themselves should not appear in the actual code).

Imagine my frustration when trying to add a ListView control whose syntax is shown as:

LV := GuiObj.Add("ListView", Options, ["ColumnTitle1","ColumnTitle2","..."])

My attempted code was

Code: Select all

pf_lv := pf.Add("ListView", "r10 count" . arrWork.Length, "Our P/N", "Vendor", "Mfg P/N", "Description")

and I kept getting an error of "too many parameters" pointing to that line. I initially thought it had something to do with the "options" section and reworked that extensively until finally just omitting it and getting the same error. Finally, reading the docs for ListView character by character I saw the example showing:

Code: Select all

; Create the ListView with two columns, Name and Size:
LV := MyGui.Add("ListView", "r20 w700", ["Name","Size (KB)"])

Wait a minute ... you mean the square brackets are actually required???

How was this different than Format? Close examination revealed that the brackets in Format were a different color in the docs than the rest of the text. They also start before a comma, rather than after. Ok, perhaps that's it, but where is this documented. Perhaps it's here, somewhere, but I couldn't find it. All I found was the above mentioned rule in Concepts.

I know, you'll probably say that it's right there in the example. True, and examples are great, but you shouldn't have to go there to understand a function's syntax format. In the vast majority of instances, I can just look at the syntax guide and know how to format the line without needing an example. It is particularly easy with version 2 since everything expects expressions.

Might I suggest that anywhere square brackets are actually required within the line of code, it is pointed out explicitly immediately above or below the syntax diagram so that we know they are not just optional parameters.

Russ

[boiler]

How was this different than Format? ... They also start before a comma, rather than after. Ok, perhaps that's it, but where is this documented. Perhaps it's here, somewhere, but I couldn't find it. All I found was the above mentioned rule in Concepts.

That is where it's documented. It shows the comma preceding the optional parameters inside the brackets. Optional parameters always follow that pattern, while the ListView definition doesn't follow that pattern. The ListView syntax definition also shows quotes around literal strings inside the brackets indicating that they are elements of a simple array, not parameter names.

This is not to say there isn't merit in the idea of adding a clarifying comment, but to answer your question, it is documented, and there are multiple elements in the ListView syntax definition that indicate that it is different than the optional parameters notation.

[ntepa]

The documentation for Gui.Add also says what goes in the last parameter:

Depending on the specified control type, a string, number or an array.

[lexikos]

Most web browsers will not include the "optional" brackets when you copy syntax to the clipboard, because they are inserted by CSS rules. Did you manually type them in?

[RussF]

Most web browsers will not include the "optional" brackets when you copy syntax to the clipboard, because they are inserted by CSS rules. Did you manually type them in?

Yes, I did notice that when I was creating that post and I did have to manually type them in. That was obviously another clue, but not one I discovered until then because I don't typically copy and past from the syntax bar in the docs when writing code.

Please. I don't want this to turn into an "I'm right, you're wrong" kind of thing. Yes, the hints are usually there, but they are sometimes subtle and/or buried deep. The only point that I'm trying to make is that throughout the documentation that I have looked at so far, every other single case where square brackets are shown in the syntax bar indicate optional parameters and the brackets are not used in the actual line of code. While there may be other exceptions, so far, ListView is the only one I've seen that deviates from this norm. If so, why not just add a line to the docs explicitly stating that?

Additionally, if you scroll down a little in the ListView docs to the Add method you'll see the "standard" format for documenting a syntax line where the syntax bar is shown and below that, you have:

Options
Type: String
...
Col1, Col2, ...
Type: String
...


If that "standard" were followed above that, you would have

Options
Type: String
...
["ColumnTitle1","ColumnTitle2","..."]
Type: Array (or Array of Strings)
...


Finally, make no mistake, the documentation is an enormous body of work and overall exceptionally well done. Writing clear documentation for code is usually more challenging than writing the code itself and I commend the authors. I'm merely pointing out what I found to be somewhat ambiguous and offered a suggestion to clarify it. After all, isn't that why this forum section exists?

Cheers,

Russ

[boiler]

As I said:

This is not to say there isn't merit in the idea of adding a clarifying comment...

[just me]

Like already done for DropDownList and ListBox (though not for ComboBox) we could add something like

In this case, the last parameter of MyGui.Add is an Array like ["Choice1","Choice2","Choice3"].

to the ListView description.

[RussF]

That's funny! I just now happened to look up DDLs for another reason and saw that. I came over to the forum to mention it and you beat me to it. That addition would be perfect!

Russ