On 3/21/2015 12:41 AM, Serhiy Storchaka wrote:
How to document functions with optional positional parameters?
For example binascii.crc32(). It has two positional parameters, one is mandatory, and one is optional with default value 0. With Argument Clinic its signature is crc32(data, crc=0, /). In the documentation it is written as crc32(data[, crc]) (and noted that the default value of the second parameter is 0). Both are not valid Python syntax. Can the documentation be change to crc32(data, crc=0)?
I think the docs should be using / as well.
https://bugs.python.org/issue21488 (changed encode(obj, encoding='ascii', errors='strict') to encode(obj, [encoding[, errors]]))
https://bugs.python.org/issue22832 (changed ioctl(fd, op[, arg[, mutate_flag]]) to ioctl(fd, request, arg=0, mutate_flag=True))
https://bugs.python.org/issue22341 (discussed changing crc32(data[, crc]) to crc32(data, crc=0))