[docs] [issue32770] collections.counter examples are misleading

[Anthony Flury]

New submission from Anthony Flury <anthony.flury at btinternet.com>:

The first example given for collections.Counter is misleading - the documentation ideally should show the 'best' (one and only one) way to do something and the example is this : 

>>> # Tally occurrences of words in a list
>>> cnt = Counter()
>>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:
...     cnt[word] += 1
>>> cnt
Counter({'blue': 3, 'red': 2, 'green': 1})

clearly this could simply be : 

>>> # Tally occurrences of words in a list
>>> cnt = Counter(['red', 'blue', 'red', 'green', 'blue', 'blue'])
>>> cnt
Counter({'blue': 3, 'red': 2, 'green': 1})

(i.e. the iteration through the array is unneeded in this example).

The 2nd example is better in showing the 'entry-level' use of the Counter class.

There possibly does need to be a simple example of when you might manually increment the Counter class - but I don't think that the examples given illustrate that in a useful way; and I personally haven't come across a use-case for manually incrementing the Counter class entires that couldn't be accomplished with a comprehension or generator expression passed directly to the Counter constructor.

----------
assignee: docs at python
components: Documentation
messages: 311630
nosy: anthony-flury, docs at python
priority: normal
severity: normal
status: open
title: collections.counter examples are misleading
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue32770>
_______________________________________