Re: Package proposal Science_Weather

lists@zyanka.li wrote:

Hi Greg, ok, sounds like an idea, not to extend PEAR, I thought that it would be required for a class and I didn't know about Cache_Lite not extending it also. The problem though is, that I need to check for errors the other packages throw, so I could write my own isError, but well... where is the point where I reinvent the wheel... as I don't use the destructor, I don't think that the overhead is that huge - or is it? It is, apparently. I haven't benchmarked, but if you're curious, you should try it out :)

Concerning the sparse documentation, I started the class 2 days ago, so I was only coding and did this function descriptions only for convenienve to already have them in the file, I'm pretty well aware, that it needs a bit of verbosity ;-) I'd like to comment on a few points you made...: understand :)

On Fri, Aug 22, 2003 at 02:41:28AM -0400, Greg Beaver wrote:

[...] Could you provide a link to the page on weather.com that relates specifically to this data, or at least describe in the @param tags what they are (something like "partnerID is the username assigned by weather.com" or "partnerID is your email address" - or whatever it is :)

No, the documentation is all contained in the SDK provided by weather.com, and yes, it's a static URL, maybe I'll post it here later. Anway, on Just place the url in the docs

@link http://www.weather.com/static/url (or whatever)

well, I'm throwing different errors in the same function... multiple @throw-lines then? Haven't looked it up in the phpdoc-code... but noted... yes, exactly.

The @return tag for function getUnits($id = "", $unitsFormat = "") should be @return array, not @return mixed. In addition, please document each of the possible returns, since it's pretty clear that there is a limited set of returns, and it's a little tricky to figure it out just by reading the source (plus phpDocumentor-generated docs will be more readable).

I disagree, because I'm returning errors as well, so we're having arrays and objects. OK, try this format:

@return Science_Weather_Error|array PhpDocumentor is smart enough to split a type on | and link to any classes found.

Your code is extremely clear, and follows CS to the T. I will be very enthusiastic when the documentation matches this level of excellence :).

Like http://www.pc4p.net/pc4p/apidoc/ ;-) No offense to your documentation style and choice of language, which is great, but no, not like that :). Like this:

http://www.phpdoc.org/manual.php <ad type="shameless">Of course, I am biased, having put lots of sweat and blood into phpDocumentor, but you should know that phpDocumentor != PHPDoc. The difference is that phpDocumentor is still maintained and both works and has more output choices.</ad> ;) Greg