Annotate and document `world.py`

[knutnergaard]

@benkiel I know this wasn't on the list of needed improvements, but I couldn't see why not, and so I just did it anyway.

The examples here are in a different style than elsewhere. I would suggest changing them for consistency, but I've (mostly) kept them as is.