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.String := Format(FormatStr [, Values...])
This is even documented in Concepts->Functions:
Imagine my frustration when trying to add a ListView control whose syntax is shown as: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).
My attempted code wasLV := GuiObj.Add("ListView", Options, ["ColumnTitle1","ColumnTitle2","..."])
Code: Select all
pf_lv := pf.Add("ListView", "r10 count" . arrWork.Length, "Our P/N", "Vendor", "Mfg P/N", "Description")
Code: Select all
; Create the ListView with two columns, Name and Size:
LV := MyGui.Add("ListView", "r20 w700", ["Name","Size (KB)"])
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