For everyone out there that has found the API documentation that comes with some of the PHP class libraries out there confusing, this new article on phpPatterns.com might help to shed some light.

Understanding API Docs: how to RTFM talks about the differences between the amazing PHP Manual and the docs that come with a lot of the PHP classes out there today (or lack there of). One of these documentation methods is the "API doc" that shows you how to interact with the code already in the class. This kind of documentation is a wonderful thing, especially if you just want to use the class for a quick and ditry script, and don't want to dive into the code just to figure out how it works.

He gives a few examples of how this kind of documentation can be used, and how to understand what it's saying, and he even links to some great documentation software called phpDocumentor that can make docs for you out of specially-formatted comments already in your code.