The SugarCube v2 Documentation entry for the Dialog API's "open" call Dialog.open is currently ambiguous as to how to define the parameters for the options and closeFn placeholders, particularly for new users who are just picking up Twine and have little or no experience with JavaScript or other programming languages, and the only code example provided is simply Dialog.open(); without comments or variation.
Since some languages and CLIs require calls and definitions on-use for every formal parameter or placeholder that isn't fully predefined, and can require those calls and definitions made in different ways, this ambiguity can cause confusion for users who aren't strictly familiar with whichever one they're using at a given moment. For example the subsection header for the entry in question, Dialog.open([options [, closeFn]]) → Dialog object, led me to think that use of closeFn here wanted either Dialog.open(options(closeFn())); or, if it was a typo, Dialog.open(options(),closeFn()); with potential definitions of (options(null, closeFn(null))); or (options = null, closeFn = [function]); whereas I was later told in the Twine Discord server that it wants the placeholder calls bypassed entirely (ex. Display.open(null, [function]);).
Can you please clarify both here and in a near-future update of the Documentation what is the correct parametric syntax for Dialog.open and provide code examples for new users?
The SugarCube v2 Documentation entry for the Dialog API's "open" call
Dialog.openis currently ambiguous as to how to define the parameters for theoptionsandcloseFnplaceholders, particularly for new users who are just picking up Twine and have little or no experience with JavaScript or other programming languages, and the only code example provided is simplyDialog.open();without comments or variation.Since some languages and CLIs require calls and definitions on-use for every formal parameter or placeholder that isn't fully predefined, and can require those calls and definitions made in different ways, this ambiguity can cause confusion for users who aren't strictly familiar with whichever one they're using at a given moment. For example the subsection header for the entry in question,
Dialog.open([options [, closeFn]]) → Dialog object, led me to think that use of closeFn here wanted eitherDialog.open(options(closeFn()));or, if it was a typo,Dialog.open(options(),closeFn());with potential definitions of(options(null, closeFn(null)));or(options = null, closeFn = [function]);whereas I was later told in the Twine Discord server that it wants the placeholder calls bypassed entirely (ex.Display.open(null, [function]);).Can you please clarify both here and in a near-future update of the Documentation what is the correct parametric syntax for
Dialog.openand provide code examples for new users?Thank you very much. Your time is appreciated.