Vimdoc should recognize a whole code block as special and not try to pick directives, parameter names, or any special symbols out of it.
If a function does accept ..., we won't hit this case and will be silently adding bogus arguments into the vimdoc. We can work around this case in the short term with an explicit @usage.
We could tighten the regex to not accept foo[bar] or [bar]foo and avoid some false positives. That might break potentially useful syntax like "[foo]s" or "[foo]-like", but that's probably poor style and rare in practice anyway.
We might want to add syntax to escape brackets with backslashes. (Note: vim help files will still highlight them as args unless we dump literal backslashes in the generated docs).
...
As far as tightening the regex:
We could tighten the regex to not accept foo[bar] or [bar]foo and avoid some false positives. That might break potentially useful syntax like "[foo]s" or "[foo]-like", but that's probably poor style and rare in practice anyway.
I did run into a real-world case for looser matching: syntax like [foo]'s is occasionally useful. For example:
" Gets absolute file path to [path]'s package directory.
It's not an "absolute must" to support syntax like that, but now we have a non-contrived case where it would be useful.
...
As far as tightening the regex:
I did run into a real-world case for looser matching: syntax like [foo]'s is occasionally useful. For example:
It's not an "absolute must" to support syntax like that, but now we have a non-contrived case where it would be useful.