Review bpo-13386: Document documentation conventions for optional args
iritkatriel opened this issue · comments
This is an old issue which I believe is within the remit of the docs WG. (Please correct me if I am misunderstanding what the WG does).
It seems, from at least a brief overview of the documentation that this most likely effects (builtins, io, os, etc), that modern usage of positional-only arguments is more limited than in the past, and keyword notation is used more consistently for functions that actually take such, at least more so than in the past, where I can recall lots of functions that took keywords but still used [] and number of instances of ]s nested many levels deep, which I found noisy, ugly and hard to read and parse—in fact, I even recall opening an issue about it back in the day due to my confusion over it.
However, this still seems worth reviewing, since there still seems to be a number of instances where [] notation is used when keyword=default notation should be used instead, e.g. in the socket docs for functions that I can confirm do indeed take keyword arguments. It might be worth going over this more broadly.
Also, to note, we now have / to indicate positional-only parameters in the function signature, which (at least to me) reads a lot cleaner and clearer than the old bracket notation, not to mention is much more consistent with both the actual Python signature, and the documentation of most if not all non-stdlib functions that do truly use them. But that's a much bigger change, and would need to be explained somewhere prominent such that docs readers are more likely to see them, perhaps along with keyword-only notation (e.g. by linking the FAQ entry).
This is now python/cpython#57595, discussion should happen on that issue as noted in the May 2022 meeting.
A