Re: experimental features?

Lukas Smith wrote: > Greg Beaver wrote: > >> Lukas Smith wrote: >> >>> Hi, >>> >>> 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. > > > Good thing that all packages have API documentation :) > > Anyways: what would be the appropriate PHPDoc comment? I would do something non-fancy like: /** * do blah - EXPERIMENTAL * * WARNING: this function is experimental and may change signature at * any time until labelled as non-experimental * * blah blah blah * ... */ phpDocumentor doesn't yet have the capability to separate things by stability within a package, just by package/subpackage. You could get fancy and use a @subpackage EXPERIMENTAL and group all experimental stuff that way, so that it appears on the left-hand index in its own grouping. Greg