dukeofgaming wrote:
So, please stop saying "no" to every feature request that comes
in and
start to discuss the actual impact of each feature.
I think that MY only problem with you 'adding annotations because it
is missing' is simply that I've already been doing it for years -
just not calling it 'annotations' ... its 'documentation' and always
has been ...
It is really troubling to read that statement. Seems there are still
some that don't really have a clue of what annotations are, even when
the RFC clearly links to them. Annotations ARE NOT documentation; in the
case of PHP, documentation is being used as annotations because there is
no language implementation, which exists in other languages (Java, .NET)
and they are widely used. Also, some use annotations as documentation
(e.g. store the class version), but again, annotations ARE NOT
documentation. Don't let the "@" notation shared with docblock fool you.
Guilherme, I think its easy to assume that people already have some
sense of what annotations are, but perhaps the wiki entry could be more
educational about it?. The first time I read about annotations it was
from this link:
http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html;
perhaps an intro like that could help to make the case for annotations
crystal clear?.
But that aligns perfectly with my interpretation of 'annotations' - compiler
time commands and control - but we do not compile - we run the files raw.
It even say ...
Documentation
Many annotations replace what would otherwise have been comments in code.
And I can't see why the @interface complexity can't simply be replaced with the
existing docblock header which already has the same data contained. However that
is only part of the picture and passing information on parameters is what I am
seeing as the main use of annotation? ( this is probably going to wrap )
/**
* registerPackageUpgrade
*
* @param array $pParams Hash of information about upgrade
* @param string $pParams[package] Name of package that is upgrading
* @param string $pParams[version] Version of this upgrade
* @param string $pParams[description] Description of what the upgrade
does
* @param string $pParams[post_upgrade] Textual note of stuff that
needs to be observed after the upgrade
* @param array $pUpgradeHash Hash of update rules. See existing
upgrades on how this works.
* @access public
* @return void
*/
function registerPackageUpgrade( $pParams, $pUpgradeHash = array() ) {
No doubt this could be automatically processed to to provide a java like view of
the same information, but what am I missing here? The data is already contained
in the code ... existing tools handle and display it ... but it is still easily
edited and read by any existing user?
Of cause doxygen requires a slightly different dialect to phpdoc, and THAT is
something that it would be worth investigating, but that is a different problem.
--
Lester Caine - G8HFL
-----------------------------
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk//
Firebird - http://www.firebirdsql.org/index.php
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
