At Least One Example for Every Method, Function, and Class

[crantila]

Every method, function, and class needs at least one example of a real-world use case.

Although it's not written in Python, the Qt API documentation is an excellent model. For example, http://qt-project.org/doc/qt-5.1/qtnetwork/qdnslookup.html

[crantila]

I have a very specific format in mind---unfortunately not present in any of our current documentation.

Kind of like AggregatedPiece.get_data(), but with the parameters, returns, and raises appearing after the brief description, and the examples appearing last.

Kind of like FilterByOffsetIndexer, but again re-ordered, and you probably want to emphasize Python-language examples most of the time.

This is my understanding of what Qt does.

These examples must be written in the docstrings of the source files themselves.