yaml.load docstring doesn't imply it will only handle single-document streams

[nbrunett]

It seems misleading to me that the yaml.load docstring reads "Parse the first YAML document in a stream..." (emphasis mine) because it implies a multi-document stream can be loaded with this method and only the first document will be parsed. This is not the case though, e.g.

documents = """
---
name: The Set of Gauntlets 'Pauraegen'
description: >
    A set of handgear with sparks that crackle
    across its knuckleguards.
---
name: The Set of Gauntlets 'Paurnen'
description: >
  A set of gauntlets that gives off a foul,
  acrid odour yet remains untarnished.
---
name: The Set of Gauntlets 'Paurnimmen'
description: >
  A set of handgear, freezing with unnatural cold.
"""
yaml.load(documents)

results in the following error.

yaml.composer.ComposerError: expected a single document in the stream
  in "<unicode string>", line 3, column 1:
    name: The Set of Gauntlets 'Paur ...
    ^
but found another document
  in "<unicode string>", line 7, column 1:
    ---
    ^

If it instead said something like "Parse a single-document YAML stream..." I think I would have inferred I could not pass it a multi-document stream. Maybe a better approach would be to make it explicit so no inference would be needed, with something like the following.

Parse a single-document YAML stream and
produce the corresponding Python object. To
load a multi-document YAML stream refer to
`yaml.load_all`.

It looks like the same applies to these additional methods too.

• yaml.compose
• yaml.full_load
• yaml.safe_load
• yaml.unsafe_load