Re: experimental features?
| From: | Lukas Smith | Date: | Thu, 13 Jul 2006 15:33:01 +0000 |
| Subject: | Re: experimental features? | ||
| References: | 1 2 | Groups: | php.pear.dev |
| Request: | Send a blank email to pear-dev+get-43466@lists.php.net to get a copy of this message | ||
Greg Beaver wrote:
Lukas Smith wrote:Good thing that all packages have API documentation :) Anyways: what would be the appropriate PHPDoc comment? regards, LukasHi, I am wondering how I should deal with new experimental features in MDB2? Am I allowed to mark a feature as experimental in the phpdoc comments and the changelog? In which case I am allowed to later change the API, eventhough the feature was released as part of a stable version?This is a *perfect* example of why documentation is so important and powerful. People can tell that by using a feature, it is not stable even though the rest of the package is stable, and yes, this means that you are free to change it. Once something is documented as stable, it can't be broken. This also implies that any package with a "stable" state that doesn't have a documented API is in fact unstable because no API is defined at all and is the reason why we have a major problem when this occurs in PEAR.