Optional Function Parameters in Computer Language Docs (the idiocy thereof)
there's a common idiocy among tech geekers in documentation. For example, from [ http://docs.python.org/3.0/library/bisect.html ] ,
LOOK:
![python 3 bisect doc](i/python_3_bisect_doc.png)
bisect.bisect_left(list, item[, lo[, hi]])
this is unreadable and confusing, especially because square brackets are valid syntax in the lang.
the tech geeking idiots write it that way because, writing it that way makes them computer scientists. It came from certain BNF. In particular, pythoners live in a world of “comp sci R us”.
what it means is this, any one of the following:
bisect.bisect_left(list, item) bisect.bisect_left(list, item , lo) bisect.bisect_left(list, item , lo, hi)
Here is another example, from PHP
![php doc preg grep](i/php_doc_preg_grep.png)
array preg_grep ( string $pattern , array $input [, int $flags = 0 ] )
![mozilla doc settimeout 2019-04-25 x72gm](i/mozilla_doc_settimeout_2019-04-25_x72gm.png)
Solution
which lang doc does it properly?
Wolfram Language.
![Wolfram Language Table doc](i/Wolfram_Language_Table_doc.png)
and JavaScript doc by Microsoft. [see Examples of Quality Documentation in Computing Industry]
Addendum. In python doc for version 2.7 and 3.1 and later, they corrected this.
Now they write it like this:
bisect.bisect_left(a, x, lo=0, hi=len(a))
.
(2013-02-25 Thanks to Yuri Khan.)