Android :: Documentation - Especially In The Dev Guide Category

I have been using the Android documentation for a few days now, and it is quite good and easy to read. Apart from that I noticed that I missed something, and now I found out what it is: Examples and comments.

If you look at the PHP documentation (e.g. http://www.php.net/manual/en/function.substr.php for the PHP substr() function) you will see many syntax-highlighted examples and comments by users.

Of course there are examples in the Android documentation, especially in the Dev Guide category - they just are not at the right place if one searches the reference for a specific method or functionality. What do you think about this?