Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:64727
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain hoa-project.net from 95.130.12.24 cause and error)
Message-ID: <50ED5BB7.6060207@hoa-project.net>
Date: Wed, 09 Jan 2013 12:59:51 +0100
Reply-To: ivan.enderlin@hoa-project.net
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:20.0) Gecko/20100101 Thunderbird/20.0a2
MIME-Version: 1.0
To: internals@lists.php.net
References: <50ED4C18.3090806@zerocue.com>
In-Reply-To: <50ED4C18.3090806@zerocue.com>
Content-Type: multipart/alternative;
 boundary="------------090400050507000700010104"
Subject: Re: [PHP-DEV] - True Annotations
From: ivan.enderlin@hoa-project.net ("Ivan Enderlin @ Hoa")

--------------090400050507000700010104
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Hi internals,

I would like to give you my thoughts about annotations.

An annotation *must not change* the code *behavior* but add a useful 
*information* for the users or *tools*.

The syntax used most of the time is very restrictive (such as 
Foo('Bar'), DateType('datetime'), MinLength(42) etc.). We cannot express 
any logic formula, disjunction, conjunction or anything else. There are 
other *annotation* and *specification* languages, that exist for PHP and 
that are much more complete. So, the referenced RFC is very very 
restrictive. The purpose of annotations could be larger than "weakly 
type" some data, because it can contain informations of very different 
natures.

Fortunately, there is a common syntax between all existing ones. In Java 
or PHP, we use the @ symbol to introduce a keyword, followed by a 
description. The set of keywords with their descriptions is an 
annotation. For instance: @param, @return, @requires, @ensures, 
@throwable etc. The @ symbol can be different but it is not the purpose 
for now. So, if PHP would propose an API, it would be a way to get the 
description of a keyword. Something like: 
$reflectionAnnotation->getValue('requires') for example, or 
$reflectionAnnotation['requires']. Then, *it is part* to the user or the 
tool to *analyse* (maybe to parse) the description of the keyword to 
give it a *semantics*. It would be a compromise between all existing 
implementations and languages, but it will not close the door to more 
sophisticated annotation or specification languages.
The fact that it is part to the user or the tool to analyse the 
description is not a bad thing. Analyzing annotations should be static, 
not dynamic (i.e. during the runtime). Maybe there are different points 
of view but as annotations must not change the code behavior, runtime 
use cases are very rare.

Then, there is also a confusion between *API documentation* (not just 
simple documentation) and annotations. API documentation is an 
annotation. It does not change the code behavior, it is a useful 
information for users and tools, so *it is an annotation*. There is 
different API documentation syntaxes (or languages), but most of them 
also introduce descriptions by the @ symbol combined with a keyword, so 
it respects my previous words.

As an example of what kind of annotations we are able to have: 
contracts. This is a more complex example of a specification. It does 
not change the code behavior, it is a very important information for the 
user and some tools that automate the test process (by making 
contract-based testing or the design-by-contract paradigm).

So, to summarize myself, I propose that PHP has a native parser for the 
following annotation grammar (not in a formal syntax):

     @keyword description;

Maybe, a description can be a block, thus we have:

     @keyword { description }

And in the description, we could have other keywords:

     @keyword {
         @key description;
         @word description;
     }

It also could be useful to label/index the keyword, maybe by using the 
following syntax:

     @keyword[label] description;

It could fit the most existing use cases around without closing the door 
to "exotic" (i.e. not common) ones, such as contracts or alike 
specifications.

Best regards.



On 09/01/13 11:53, Clint Priest wrote:
> Just starting a new thread here to discuss true annotations vs a 
> DocBlock Parser:
>
> RFC Referenced:
>
> https://wiki.php.net/rfc/annotations
>
>
> On 1/9/2013 2:09 AM, Peter Cowburn wrote:
>> On 9 January 2013 01:08, Rasmus Schultz <rasmus@mindplay.dk> wrote:
>>> I've started working on a new proposal, but I'm getting hung up on the
>>> syntax - if we can't use angle brackets anymore, what can we use? 
>>> Virtually
>>> every symbol on a standard US keyword is an operator of some sort, does
>>> that mean those are all out of the question?
>>>
>>> e.g. thinking of concrete possible basic syntax, neither of the 
>>> following
>>> delimiters would work:
>>>
>>> [Foo('bar')]
>> Why would this not work? I'm struggling to think of a place where one
>> would want to use an annotation where it could be misinterpreted as an
>> array literal.  If anything, the visual "conflict" or association with
>> the array syntax is a good thing in my book: my brain parses it as an
>> array of one or more annotations.
> I agree here, I think the above, if possible would be best.  In my 
> mind annotations should proabably be limited in scope to class 
> declarations and thus only before a class keyword, before a property 
> or method declaration.
>
> In none of those scopes would [ ] be a parsing issue I believe...
>
> The one case would be at the beginning of a class, but if simply added 
> something such as:
> [:SomeAttribute(xyz,abc),SomeAttribute2]
>
> It could never be confused with short array syntax and is still brief.
>

-- 
Ivan Enderlin
Developer of Hoa
http://hoa.42/ or http://hoa-project.net/

PhD. student at DISC/Femto-ST (Vesontio) and INRIA (Cassis)
http://disc.univ-fcomte.fr/ and http://www.inria.fr/

Member of HTML and WebApps Working Group of W3C
http://w3.org/


--------------090400050507000700010104--