[issue23549] heapq docs should be more precise about how to access the smallest element

[Eli Bendersky]

New submission from Eli Bendersky:

The heapq documentation has this paragraph after the doc of nsmallest:

  The latter two functions perform best for smaller values of n. For larger values, it is more efficient to use the sorted() function. Also, when n==1, it is more efficient to use the built-in min() and max() functions.

This is confusing as it suggests to use min() on a heap to find the minimal element.

heap[0] is the minimal element, but this is only mentioned at the very top - so you need to read the doc of the entire module to find it. Nothing in the docs of methods suggests it.

----------
assignee: docs at python
components: Documentation
messages: 236895
nosy: docs at python, eli.bendersky
priority: normal
severity: normal
status: open
title: heapq docs should be more precise about how to access the smallest element
type: behavior
versions: Python 2.7, Python 3.4, Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue23549>
_______________________________________