A wise colleague of mine (geekyMoa, http://drupal.org/user/1097732), pointed out that api.drupal.org would be much more useful if there were more examples on how to use functions. This is apparently how WordPress has their documentation, and I know php.net has the same thing (and their examples have certainly been useful to me).
I dug around a bit to find prior discussion on this topic, and could find the following threads:
#576964: Examples in the API Doc →
#547534: Review "Commenting on handbook pages and API pages" →
(in particular comments 21, 31, 38, and 41).
I know there are other kinds of comments at api.drupal.org right now, but I can't recall ever having any use of them (and to frank, questions posted as comments on api.drupal.org very seldom get answered). Using comments for examples would, I think, make api.drupal.org much more useful.
I hereby suggest that we start officially using comments on api.drupal.org for posting examples, and make changes in the interface to make this clear.
Closed: outdated
1.0
Code
Issue summaries save everyone time if they are kept up-to-date. See Update issue summary task instructions.
Not all content is available!
It's likely this issue predates Contrib.social: some issue and comment data are missing.
Comments were closed a few months ago, so the comments form went away.
This issue is in "needs review" 🐛 Restore link for filing a documentation issue Needs review and is for the new version of the site if somebody wants to review the wording.