Example snippets for simpler functions/methods

[kishvanchee]

BPO	37557
Nosy	@rhettinger, @kishvanchee

^{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 2019-07-13.06:03:42.632>
created_at = <Date 2019-07-11.06:49:39.207>
labels = ['type-feature', 'docs']
title = 'Example snippets for simpler functions/methods'
updated_at = <Date 2019-07-13.06:03:42.618>
user = 'https://github.com/kishvanchee'

bugs.python.org fields:

activity = <Date 2019-07-13.06:03:42.618>
actor = 'rhettinger'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-07-13.06:03:42.632>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2019-07-11.06:49:39.207>
creator = 'kishvanchee'
dependencies = []
files = []
hgrepos = []
issue_num = 37557
keywords = []
message_count = 2.0
messages = ['347656', '347776']
nosy_count = 3.0
nosy_names = ['rhettinger', 'docs@python', 'kishvanchee']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue37557'
versions = []

[kishvanchee]

Is there a reason why many (not all) of the simpler methods lack example snippets?

Snippets which are present:

1. https://docs.python.org/3/library/stdtypes.html#str.rstrip
2. https://docs.python.org/3/library/stdtypes.html#str.strip

Snippets which are not present:

1. https://docs.python.org/3/library/stdtypes.html#str.lower
2. https://docs.python.org/3/library/stdtypes.html#str.upper
3. https://docs.python.org/3/library/stdtypes.html#str.isupper

Is there any recommendation against adding concise example snippets for all methods?

I am of the opinion that short examples are more easier to read and visually skim through, than reading the description. I was hoping I could add example snippets to the simpler methods if anyone does not have any objection towards it.

[rhettinger]

We generally only put the examples where they add something substantive. Otherwise, it just make the docs verbose and time consuming to read start to finish.

Adding an example for str.lower() contributes no additional value. Most published Python books would all avoid the unnecessary here as well. FWIW, we have no evidence that any user has ever found the current form hard to use.

So, let's close this. If you're looking for places to contribute, please look at the open bugs where there are known problems.