Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:52273
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain lsces.co.uk from 213.123.26.187 cause and error)
Message-ID: <4DCA38E6.9020003@lsces.co.uk>
Date: Wed, 11 May 2011 08:21:10 +0100
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.18) Gecko/20110320 SUSE/2.0.13-1.2 SeaMonkey/2.0.13
MIME-Version: 1.0
To: PHP internals <internals@lists.php.net>
References: <4DC729EE.9090600@sugarcrm.com> <4DC75FFF.40008@lerdorf.com> <4DC7A7F0.4000504@sugarcrm.com> <BANLkTinn3+MCrSd7BAJCU03FMkuRAeydvA@mail.gmail.com> <4DC819D0.5010008@lerdorf.com> <BANLkTi=K8vc3wvwkKVtLS9o0Oh0itB_dTg@mail.gmail.com> <4DC81ED6.1050902@sugarcrm.com> <BANLkTikhJ1Z0Gk-cSivoFBFs1Fx8CHz=mA@mail.gmail.com> <8757232E56758B42B2EE4F9D2CA019C9013F9F59@US-EX2.zend.net> <BANLkTi=0OFHjfSyv3w+3f5+gcPVV7beoeA@mail.gmail.com> <4DCA2192.4080201@lsces.co.uk> <BANLkTimpauJ3Dq4LSW+3DKXd6zznHj_-iQ@mail.gmail.com>
In-Reply-To: <BANLkTimpauJ3Dq4LSW+3DKXd6zznHj_-iQ@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] annotations again
From: lester@lsces.co.uk (Lester Caine)

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