Proposal: marking functions as deprecate (java-like) or experimental

the attached small path introduces two macros and two new configuration settings controling them PHP_DEPRECATE(version,reason); controled by warn_deprecate=on/off and PHP_EXPERIMENTAL(version,reason); controlled by ward_experimental=on/off as we go along extending and improving php, once in a while there is a function we don't need or want anymore or which is known under a name we'd like to (or even have to) change to resolve some conflict or just to prevent misunderstandings on the other hand we might introduce even more new functions (i hope so), that may be not ready for prime time and shoul d not be used by common users until tested and setteled java solves problem #1 with the 'deprecate' keyword whenever you use a class or methed marked as deprecate you'll get a compiler warning that you are using a feature that is no longer supported and that may vanish in following versions (you may, of course, turn theese warnings of (or did you have to turn them explicitley on? can't remeber)) for the php functions implemented in native c inside of Zend, php4 and php extensions i have tried to mimic javas behavior somehow with as minimal code changes as possible (release seemed to by a matter of days when i started this) after some experiments and probing around i came down to the mentioned two preprocessor macros and configuration entries that should not interfere with anything not using this new feature also included in the patch is a diff against php_imap.c that shows some example usage of this by declaring function imap_headers() as deprecate, giving some hint what to use instead, and function imap_mail_compose() as yet still experimental using these functions results in warnings unless you specify warn_deprecate=off / warn_experimental=off in your php.ini there is a small loss of one comparison for each call of a marked function even if you turned the appropriate warning of, if someone is concerned about this i might encapsulate this even more so that it can be disaled by 'configure' usage of this new feature is rather simple, you just put the appropriate macro PHP_DEPRECATE or PHP_EXPERIMENTAL into the main execution path of your function, although i'd prefer a placing as first statement after variable definitions (makes it easier to scan for this for manual generation and for my big function table ...) both macros have two parameters, version and comment 'version' should, as a string, the version - from which on a function is no longer actively supported for PHP_DEPRECATE - it first appeared in for PHP_EXPERIMENTAL 'comment' can give a reason for the functions status and a hint for a replacement for deprecate functions if comment is NULL, a default comment is generated: - "... it may be removed in future versions without further notice" for deprecate functions - "... use it at your own risk, as it might not work as expected or change without notice in the future" for experimental functions i didn't check theese changes in yet and published the attached diff instead 'cause i assume that there may be some different oppinions about the feature or the way i took for implementation but i think something like this should definetly exist, even for the only reason to prevent some stupid questions like: "whatever happend to function xyz in version a.b.c ?" "it was dropped as announced in the manual/readme/... for some time now!" "well i didn't now that, nobody asked me, i want it back!!!" comment? :)