discovery: add clarifying docstrings
Merge pull request #1610 from jonboulle/discovery_docs

discovery: add clarifying docstrings