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 <ras...@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/
