[issue37618] Docs: Code example locations in stdtypes

[Kyle Stanley]

Kyle Stanley  added the comment:

>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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37618] Docs: Code example locations in stdtypes

[Krishna Oza]

Krishna Oza  added the comment:

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.

--
nosy: +Krishna Oza, Mariatta

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37618] Docs: Code example locations in stdtypes

[Kyle Stanley]

Kyle Stanley  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue37618] Docs: Code example locations in stdtypes

[Kyle Stanley]

New submission from Kyle Stanley :

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.

--
assignee: docs@python
components: Documentation
messages: 348104
nosy: aeros167, docs@python
priority: normal
severity: normal
status: open
title: Docs: Code example locations in stdtypes
versions: Python 3.7, Python 3.8, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com