Change 1012431 had a related patch set uploaded (by Alex Paskulin; author: Alex Paskulin):

[jsdoc/wmf-theme@master] headings: Remove optional indicator

https://gerrit.wikimedia.org/r/1012431

Change #1012431 merged by jenkins-bot:

[jsdoc/wmf-theme@master] headings: Remove optional indicator

https://gerrit.wikimedia.org/r/1012431

I support this change (I think no indicator at all is better than the "opt"), but the square brackets are a fairly common convention in documentation in various languages. Another common convention, maybe more obvious, is providing the default value after a "=" sign. Here's a few examples from docs that our developers may be familiar with:

• https://www.php.net/manual/en/function.trim trim(string $string, string $characters = " \n\r\t\v\x00"): string
• https://docs.python.org/3/library/functions.html#print print(*objects, sep=' ', end='\n', file=None, flush=False)
• https://nodejs.org/docs/latest/api/child_process.html#child_processexeccommand-options-callback child_process.exec(command[, options][, callback])
• https://ruby-doc.org/3.3.0/Kernel.html#method-i-spawn spawn([env, ] command_line, options = {}) → pid

I think it's fair to say that = is used when the parameter has some meaningful default value, and [] is used when it doesn't and the behavior of the function depends on the presence of the parameter (but since it's JavaScript, it's probably close enough to use =undefined in this case).

So, considering for example the function mw.util.debounce:

• https://doc.wikimedia.org/mediawiki-core/REL1_41/js/#!/api/mw.util-method-debounce debounce( func, [wait], [immediate] ) : Function
• https://doc.wikimedia.org/mediawiki-core/master/js/module-mediawiki.util.html#.debounce debounce(func, waitopt, immediateopt) → {function}

I think the ideal way to display it would be something like this:

• debounce( func, wait=0, [immediate] ) → {function}, or
• debounce( func, wait=0, immediate=undefined ) → {function}

Thanks for this comment, @matmarex. I think using square brackets sounds reasonable.

I worry about displaying defaults since we occasionally have really long defaults (see bugsLink on mw.Feedback) that would be noisy to display in a heading.

I looked into adding square brackets, but it wasn't trivial, so I opened T361154 to follow up.