I am going to give some inline answers to assist with context,
On Mon, Oct 1, 2012 at 8:56 PM, Johannes Schmitt <schmi...@gmail.com
> Allowing to define custom doc types sounds like a good enhancement to me,
> some questions:
> - What would the scope of these custom doc types be (global/all files, file
> only, class only, method only)?
Good question, I'd be adverse to having global Custom Doc Types as
that can easily lead to confusion.
Not in the least place where to find the definition. Also, if you need
a Custom Doc Type in more than one
class I'd _seriously_ consider making it a real (struct) class.
Concerning scope I am in doubt, the advantage of local scope is that
it is clear while reading a DocBlock
what is defined and it seems unnecessary to share scope between
members of a class. On the other hand
I can imagine that a getter and setter share the same Custom Doc Type
and it seems odd to duplicate the
As such I would propose that the definition can be in both local as
well as class scope, but that the usage in
a @var/@type tag should make it clear which location it is. (for
example, a single colon implies local scope
and a double colon class scope?).
> - Kind of related to the first question, where could these types be defined
> (on which code elements)?
My answer to this would be that in any location where you would be
able to use a `Type` as defined in the
PHPDoc PSR you would be able to use this.
> However, if you just use the option array in a single place, then I'd say it
> should also be possible to use an inline definition and we should not
> strictly require to define a separate type (directly use @type without
I think allowing that would add to the flexibility of this proposal; however I
would personally recommend having a separate definition. But that is
> Regarding collections, in Doctrine we currently support "array<T>" to
> describe a list of types; we chose this mainly because Java is already using
> it, for example "List<Foo> myList = new HashList<Foo>();". It could be that
> "" was used in doc comments in Java at some point when it had no generics
> support, but I have not seen this anytime recently. However, I'm open to
> solely use the "" style, it's a bit more succinct, but it also should make
> a parser a bit more complex to implement.
I have found a reference to the use of Generics in @param tags here:
But if I am reading this correctly then Java has a simplified notation
as they omit the
'array' or 'Class' keyword. Since I do not know how Generics exactly
work I find this
hard to wrap my head around.
This does however lead me to the thought that I might not be the only
one and I think
that the  notation might be more intuitive for PHP Developers since
they are used
to that being an array symbol?
> Here some examples comparing the two styles:
> Lists (keys are not insignificant, and of integer type)
> "array<Foo>", or "Foo"
> Maps (keys are significant, and of integer and/or string type)
> "array<string|integer, Foo>", or "Foo[string|integer]"
> "array<string, Foo>", or "Foo[string]"
> Multidimensional Lists:
> "array<array<string>>", or "string"
> Multidimensional Maps:
> "array<string, array<string, Foo>>", or "Foo[string][string]"
> Mixed multidimensional collections:
> "array<array<string, Foo>>", or "Foo[string]"
> After writing these, I'm not sure whether the  works that well, especially
> if you're dealing with multidimensional arrays. Regardless of which
> annotation we choose eventually, I'd opt to be consistent though and either
> use "" or "array<>", and not mix them.
I agree, I am very interested to other's opinion on which they believe
to be preferable.
Do we know if there are IDEs that support the Generic-style notation?