Re: Re: experimental features?
| From: | Raphaël Gertz | Date: | Thu, 13 Jul 2006 21:51:04 +0000 |
| Subject: | Re: Re: experimental features? | ||
| References: | 1 2 3 | Groups: | php.pear.dev |
| Request: | Send a blank email to pear-dev+get-43471@lists.php.net to get a copy of this message | ||
> Le jeudi 13 juillet 2006 22:27, Greg Beaver a écrit :
> 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.
>
Anyway, nobody answer me...
Is there somewhere a CLEAR and EASY template that LIST ALL attibutes ?
(I whould REALY be happy to find it, at least to help people understand what
mean FULL documented code (with every applying attributes correctly set))
I kniw that it's not a help channel, but I didn't find anything usefull...
Attachment: [application/pgp-signature]
Attachment: [application/pgp-signature]