It clearly mentions that it returns a string and that data is binary data. As everywhere in python, when it fails, it raises an Exception.

Sure. Either it says it or it can be inferred from something. But it doesn't have a consistent format. When I'm checking unknown function in PHP I know exactly where to look for descriptions of behavior (also how it fails when it fails and why) and information about type or arguments and return values. And if I need real life use cases I can take a look at the bottom of the page.

In Python function description is often just unscannable short blob of prose.

Like for example http://www.php.net/manual/en/function.ming-keypress.php :P

edit: I feel like the real life examples in the PHP docs are very nice, but not really missing in Python (there are a lot examples in the Python documentation but not for such trivial functions). In python you just start the interactive interpreter and do "import module", "module.function(xyz)" and you see exactly what's going on. It's then a copy&paste away from your shell to your editor.

I'm not saying that PHP docs couldn't be better or more complete. Some (not only but usually less commonly used) modules are barely documented at all.

It's bit strange strange that you gave undocumented function as an example of how PHP functions are documented. :-)

This difference between Python docs and PHP docs is just the thing I noticed when I started having fun with Python which is btw awesome language though finding which lib to use for given task sometimes is hard.

Good thing to do to find out what python function does is running help(module_name.function_name) in interpreter.

I'd say both documentations are very complete but take a different approach. Very often the python standard library is very self-descriptive and it's just doing what you would expect. If you're in doubt you can always start up bpython and have an autocompleted shell. That python has an interactive interpreter really is very convenient.