Re: cvs: pear /Net_Monitor Monitor.php /Net_Monitor/Monitor Alert.php Service.php /Net_Monitor/Monitor/Alert SMS.php SMTP.php
/Net_Monitor/Monitor/Service DNS.php FTP.php HTTP.php HTTPS.php SMTP.php

Hello Everyone (and Robert in particular): Several recent commits seem to indicate some misunderstanding on how to implement the header blocks. As per http://pear.php.net/manual/en/standards.header.php, the transition policy is as follows: New Packages ------------ New packages and existing packages which have no releases yet must include these docblocks before their first release. Existing Small Packages ----------------------- Existing packages that have only a few files are required to adopt these docblocks before the next release. Existing Large Packages ----------------------- Existing packages with many files are encouraged to adopt the new headers as soon as possible. When such packages come out with a new major version upgrade, these docblocks must be implemented therein. Also note how the old style header comments are no longer included. So, please remove them from your files. In addition, please take a moment to read the newly renamed "Sample File (including Docblock Comment standards)" section of the Coding Standards at http://pear.php.net/manual/en/standards.sample.php Below are some specific comments to Richard... On Tue, Mar 29, 2005 at 12:25:58AM -0000, Robert Peake wrote: > cyberscribe Mon Mar 28 19:25:58 2005 EDT > > Added files: > /pear/Net_Monitor Monitor.php > /pear/Net_Monitor/Monitor Alert.php Service.php > /pear/Net_Monitor/Monitor/Alert SMS.php SMTP.php > /pear/Net_Monitor/Monitor/Service DNS.php FTP.php HTTP.php > HTTPS.php SMTP.php > Log: > First release since proposal approval > > > > > http://cvs.php.net/co.php/pear/Net_Monitor/Monitor.php?r=1.1&p=1 > Index: pear/Net_Monitor/Monitor.php > +++ pear/Net_Monitor/Monitor.php > <?php > // +----------------------------------------------------------------------+ > // | PHP Version 4 | > // +----------------------------------------------------------------------+ > // | Copyright (c) 1997-2004 The PHP Group | > // +----------------------------------------------------------------------+ > // | This source file is subject to version 3.0 of the PHP license, | > // | that is bundled with this package in the file LICENSE, and is | > // | available at through the world-wide-web at | > // | http://www.php.net/license/3_0.txt. > | > // | If you did not receive a copy of the PHP license and are unable to | > // | obtain it through the world-wide-web, please send a note to | > // | license@php.net so we can mail you a copy immediately. | > // +----------------------------------------------------------------------+ > // | Author: Robert Peake <robert@peakepro.com> | > // +----------------------------------------------------------------------+ > // > // $Id: Monitor.php,v 1.1 2005/03/29 00:25:58 cyberscribe Exp $ > // > // Remote service monitor > /** > * Net_Monitor > * > * A unified interface for checking the availability services on external > * servers and sending meaningful alerts through a variety of media if a > * service becomes unavailable. > * > * @package Net_Monitor > * @author Robert Peake <robert@peakepro.com> > * @copyright 2004 > * @license http://www.php.net/license/3_0.txt > * @version 0.0.6 (proposal) > * > */ > /** > * Requires the main Pear class > */ > require_once 'PEAR.php'; > > /** > * class Net_Monitor > * > * @access public > * @package Net_Monitor > */ > class Net_Monitor Richard, so ditch the old header comments and flesh out and correct the docblocks for the file and class. > /** > * function check > * > * Checks the specified SMTP (email delivery) server for availability. > * Returns false on success, or a notification array on failure. > * > * @param mixed host > * @return mixed > */ > function check($host) > { > $response = 0; > $this->_client = new Net_SMTP($host); > $c = $this->_client; > $e = $c->connect(); > if (!PEAR::isError($e)) { //everything is OK > $c->disconnect(); > $this->_last_code = 200; //set last code to 200 > return false; //false signifies no problem > } else { //return connection-specific error string > $this->_last_code = $response; > return array('host' => $host, 'service' => > $this->_service, 'message' => $e->getMessage(), 'code' => > $response); > } > } A few issues stand out here, Richard. The short description of "function check" is redundant. When looking at the output, one knows they're looking at a method. (By the way, functions inside classes are called "methods.") So, the first sentence of your long description should be brought up to be the short description. Then, the second sentence in the long description would be better placed in the @return tag. Finally, the nesting above is VERY erratic. Nest with four _spaces_ per level. By the way, don't use tabs. Thanks, --Dan -- T H E A N A L Y S I S A N D S O L U T I O N S C O M P A N Y data intensive web and database programming http://www.AnalysisAndSolutions.com/ 4015 7th Ave #4, Brooklyn NY 11232 v: 718-854-0335 f: 718-854-0409