classification
Title: Docs: Code example locations in stdtypes
Type: Stage:
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Krishna Oza, Mariatta, aeros, docs@python
Priority: normal Keywords:

Created on 2019-07-18 07:42 by aeros, last changed 2019-07-19 20:22 by aeros.

Messages (4)
msg348104 - (view) Author: Kyle Stanley (aeros) * (Python committer) Date: 2019-07-18 07:42
In the docs for the module stdtypes, the code example for several commonly used functions are in the bytearray section instead of the str section, where new users are far more likely to look. The new users are much more likely to benefit from seeing examples of these functions. A few examples of this include: islower(), isupper(), and istitle(). Since the functionality is very similar for functions such as str.islower() and bytearray.islower(), it doesn't seem necessary to include separate examples for each. With that in mind, here's a couple of potential solutions:

1) Move the location of the code examples to the str equivalent. This would require only removing the 'b' notation proceeding the strings. A link to the str equivalent could be potentially provided.

2) Provide a reference link to equivalent bytearray function in the str function's summary. This would be a bit easier since the code examples would not have to me modified or moved. However, for reasons stated above, it seems to make a bit more sense to have the examples be in the str functions rather than in the bytearray functions.

I can start working on a PR to address this, but I'll wait on some feedback first.
msg348106 - (view) Author: Kyle Stanley (aeros) * (Python committer) Date: 2019-07-18 07:44
Clarification on option 1: The last sentence should be "A link to the bytearray equivalent..."

Clarification on option 2: As a part of this option, a link to the str equivalent could optionally be provided.
msg348175 - (view) Author: Krishna Oza (Krishna Oza) * Date: 2019-07-19 13:31
Kyle
In my opinion the current documentation is correctly formed since the bytearray and str are two different classes in Python they could have different set of functions supported and hence the grouping of functions like islower() to be kept separated for different object types.
msg348196 - (view) Author: Kyle Stanley (aeros) * (Python committer) Date: 2019-07-19 20:22
>In my opinion the current documentation is correctly formed since the bytearray and str are two different classes in Python they could have different set of functions supported and hence the grouping of functions like islower() to be kept separated for different object types.

This could justify the grouping of the functions themselves, but doesn't explain why the code examples are contained in bytearray instead of str. New users of the language are far more likely to check the docs for the string functions, and thus benefit significantly more from seeing the code examples.
History
Date User Action Args
2019-07-19 20:22:33aerossetmessages: + msg348196
2019-07-19 13:31:24Krishna Ozasetnosy: + Mariatta, Krishna Oza
messages: + msg348175
2019-07-18 07:44:40aerossetmessages: + msg348106
2019-07-18 07:42:29aeroscreate