Poorly documented code is one of those things that drives me insane.
Some authors out there will consider it enough to give you the generated docs from their comments in the source code, like doc blocks above methods. In my opinion, these docs are as useless as having no documentation at all. So what do I consider good documentation? That basically boils down to two things.
- Explanations of errors
That’s about it. Provide the above, and the rest of your code documentation can take a hike.
Recently I have been working with the Guzzle PHP library; a library that is poorly documented. I was running into an Exception whose body was something that looked like this.
Unfortunately for me, that error is creeping up from the underlying cURL libraries. However, one should be able to consult the Guzzle documentation for ways to work around this problem. Does such documentation exist? Not that I could find.
From what I have read, it appears that this is a problem in PHP…or the cURL bindings to PHP, not being able to read from phar files which, of course, is how Guzzle is distributed. I’m not lucky enough to be the first person to stumble across this problem (or so I thought) but my Google skills failed me.
So I had to go look at the sourcecode. The solution to the problem is to set the ssl.certificate_authority option in the client to “system”. See the example below.
$client = new Client($url, array( 'ssl.certificate_authority' => 'system', 'curl.options' => array( CURLOPT_SSL_VERIFYPEER => 0, CURLOPT_SSL_VERIFYHOST => 0, CURLOPT_CERTINFO => 0, CURLOPT_CAINFO => '' ) ));
This solution applies to the Guzzle phar with the following MD5 hash</p>
fsf@fsf-voyager:~/fsf$ md5sum lib/support/php/Guzzle.phar 5f3ac48b0cdfd399108e8669e1c7af9b lib/support/php/Guzzle.phar
In case you are wondering, I set the other cURL options to make sure that it disregards all SSL related checks.