The main reason I like the comments on php docs is it's helpful for me to see a basic usage example. A lot of docs (your typical 'man' page for instance) just have a dictionary-like wall of text without a usage sample.