Optional Function Parameters in Computer Language Docs (the idiocy thereof)

By Xah Lee. Date: . Last updated: .

there's a common idiocy among tech geekers in documentation. For example, from [ http://docs.python.org/3.0/library/bisect.html ] ,


python 3 bisect doc
Python 3.0 doc on bisect
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's another example, from PHP

php doc preg grep
PHP doc on preg_grep
array preg_grep ( string $pattern , array $input [, int $flags = 0 ] )
mozilla doc settimeout 2019-04-25 x72gm
Mozilla doc on JavaScript setTimeout 2019-04-25


which lang doc does it properly? Wolfram Language. (For example, http://reference.wolfram.com/mathematica/ref/Table.html) , JavaScript doc by Microsoft. [see Examples of Quality Documentation in Computing Industry]

Wolfram Language Table doc
Wolfram Language doc on Table

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.)

Python Documentation Sucks

  1. Python Doc Problem: os.system
  2. Python Doc Problem: os.path.split()
  3. Python Doc Problem: sort()
  4. Python Doc Problem: gzip
  5. Python Documentation Problems
  6. Python Documentation Author Masturbation
  7. How to Improve Python Doc; Notes on Rewriting Python Regex Doc
  8. Why Python's Documentation Sucks
  9. Python Poetry: the __main__ Stanza
  10. perldoc Coming of Age, What Python Can Learn From?
  11. Examples of Quality Documentation in Computing Industry
  12. Python Doc Links Dead
  13. Python Doc Links All Dead
  14. Python = Pretentious Sheet
  15. Optional Function Parameters in Computer Language Docs (the idiocy thereof)

If you have a question, put $5 at patreon and message me.