Comment by 65

I used to work on Drupal sites and they have very few examples for how to actually use various functions. So you'd run into instances where you're doing something completely wrong even if the function name makes sense.

The best documentation is type references and examples and a line explaining what the function does. Not one or the other.