Inherited docstrings for pathlib classes are confusing

[merwok]

BPO	31972
Nosy	@pitrou, @merwok, @chason, @miss-islington
PRs	bpo-31972: Improve docstrings for pathlib classes #5310 [3.6] bpo-31972: Improve docstrings for pathlib classes (GH-5310) #5749 [3.7] bpo-31972: Improve docstrings for pathlib classes (GH-5310) #5750

^{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 = 'https://github.com/merwok'
closed_at = <Date 2018-02-19.01:00:42.515>
created_at = <Date 2017-11-07.19:05:43.171>
labels = ['easy', 'type-feature', '3.8', '3.7', 'library', 'docs']
title = 'Inherited docstrings for pathlib classes are confusing'
updated_at = <Date 2018-02-19.01:01:16.857>
user = 'https://github.com/merwok'

bugs.python.org fields:

activity = <Date 2018-02-19.01:01:16.857>
actor = 'eric.araujo'
assignee = 'eric.araujo'
closed = True
closed_date = <Date 2018-02-19.01:00:42.515>
closer = 'eric.araujo'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2017-11-07.19:05:43.171>
creator = 'eric.araujo'
dependencies = []
files = []
hgrepos = []
issue_num = 31972
keywords = ['patch', 'easy']
message_count = 5.0
messages = ['305788', '312332', '312334', '312335', '312336']
nosy_count = 5.0
nosy_names = ['pitrou', 'eric.araujo', 'docs@python', 'chason.chaffin', 'miss-islington']
pr_nums = ['5310', '5749', '5750']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue31972'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[merwok]

pydoc pathlib.Path shows the docstring of PurePath:

| PurePath represents a filesystem path and offers operations which
| don't imply any actual filesystem I/O.

But immediately after we see methods like chmod, exists and co which obviously aren’t pure. Looking at the reST docs or the source code, the reader can deduce that this is the docstring of PurePath inherited by Path, but I find it confusing.

Solution: adding docstrings to all pathlib classes. PurePath and Path can have all the info, Posix/Windows* subclasses only one line with a reference.

[merwok]

New changeset dfa015c by Éric Araujo (chason) in branch 'master':
bpo-31972: Improve docstrings for pathlib classes (bpo-5310)
dfa015c

[miss-islington]

New changeset 5c81ed4 by Miss Islington (bot) in branch '3.6':
bpo-31972: Improve docstrings for pathlib classes (GH-5310)
5c81ed4

[miss-islington]

New changeset 19b7f66 by Miss Islington (bot) in branch '3.7':
bpo-31972: Improve docstrings for pathlib classes (GH-5310)
19b7f66

[merwok]

Thanks for the patch!