[Python-Dev] How to document functions with optional positional parameters?

[Terry Reedy]

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.

> Related issues:
>
> 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))
>


-- 
Terry Jan Reedy