Modernize function signature in Archiving section of shutil doc

[CAM-Gerlach]

BPO	36490
Nosy	@giampaolo, @tarekziade, @methane, @CAM-Gerlach

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-03-04.10:58:46.280>
created_at = <Date 2019-03-31.04:08:08.160>
labels = ['invalid', '3.8', 'docs']
title = 'Modernize function signature  in Archiving section of shutil doc'
updated_at = <Date 2020-03-04.10:58:46.280>
user = 'https://github.com/CAM-Gerlach'

bugs.python.org fields:

activity = <Date 2020-03-04.10:58:46.280>
actor = 'CAM-Gerlach'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-03-04.10:58:46.280>
closer = 'CAM-Gerlach'
components = ['Documentation']
creation = <Date 2019-03-31.04:08:08.160>
creator = 'CAM-Gerlach'
dependencies = []
files = []
hgrepos = []
issue_num = 36490
keywords = []
message_count = 4.0
messages = ['339243', '339279', '355866', '363343']
nosy_count = 5.0
nosy_names = ['giampaolo.rodola', 'tarek', 'methane', 'docs@python', 'CAM-Gerlach']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue36490'
versions = ['Python 3.8']

[CAM-Gerlach]

In the process of updating the documentation for another issue, I noticed that unlike the rest of the shutil doc (and the Python docs in general, not to mention those of virtually every Python package), all the functions in the Archiving operations section uses the old style, difficult to parse nested-bracket notation for the function signatures, rather then the modern style displaying them as they would be expected to appear in Python code, with clearly and explicitly indicated defaults.

Therefore, given all bracketed items are keyword arguments with defaults, and there are no cases more complex then the standard linearly-nested brackets, is there a particular reason why this was retained? Otherwise, I can go ahead and submit a PR to update this.

[methane]

I don' think they are modern-style vs legacy-style.

When explicit default value is present, the default value is documented in signature like param=42.
On the other hand, when default value is not explicit (just an placeholder), the parameter is expressed using optional group [param].

[CAM-Gerlach]

Sorry for the lack of response on this one; it just slipped off my radar. It seems quite clear that my understanding was incomplete as to why the signatures were expressed this way. As such, I presume this can just be closed as NOTABUG? I'll close in a week (assuming I remember) if I don't hear otherwise or someone else doesn't first. Thanks and sorry for bothering folks on this.

[CAM-Gerlach]

Closing on grounds of apparently not really being an issue as opposed to a misunderstanding on my part, as mentioned above.