classification
Title: Example snippets for simpler functions/methods
Type: enhancement Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, kishvanchee, rhettinger
Priority: normal Keywords:

Created on 2019-07-11 06:49 by kishvanchee, last changed 2019-07-13 06:03 by rhettinger. This issue is now closed.

Messages (2)
msg347656 - (view) Author: Kishore (kishvanchee) * Date: 2019-07-11 06:49
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.
msg347776 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-07-13 06:03
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.
History
Date User Action Args
2019-07-13 06:03:42rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg347776

resolution: rejected
stage: resolved
2019-07-11 06:49:39kishvancheecreate