[PSR-5] @var becoming @type

[Matthieu Napoli]

Hi all,

If I understood everything correctly, PSR-5 proposes to replace the @var tag with @type.

While I agree that semantically, this is more correct (and @var being a legacy of PHP 4), what happens with every code written in PHP ever that uses @var? Does that mean that this code is not PSR-5 compatible?

It seems to me like a bold move, because the gain is very little, compared to the impact on the existing code. Do we really want to have to re-write every property docblock just because "@type" makes more sense? And this also impacts greatly IDEs and tools.

I've searched the proposed PSR and meta-doc but couldn't find any explanation as to why this change. I also couldn't find any discussion about this in the mailing list. Is there any other reason behind this?

Matthieu

[Mike van Riel]

Hi Matthieu,

In PSR-5 I, and other contributors with me, propose to deprecate the
@var tag in favor of a new tag @type.

The reasons for this are:

1. @var was not designed (allowed) for constants.
2. @var was not designed (allowed) for variables and foreach.
3. @var is not usable with associative array definitions.
4. @var does not support multi-property definitions (`public $prop1,
$prop2;`).
5. The name @var refers to a PHP4 style of property definition and no
longer semantically fit the bill.

Simply put, introducing a more generic tag `@type` will permit the
PHPDoc to be more flexible. Sure
we could have repurposed the name `@var` but syntactically it is not the
same element; even if @var
is used in situations for which it was not designed.

PSR-5 explicitly *deprecates* `@var` and does not remove it. This means
that using `@var` for
properties is valid according to PSR-5; it just isn't recommended as a
next version of the specification
can remove the tag.

Kind regards,

Mike van Riel

> --
> You received this message because you are subscribed to the Google
> Groups "PHP Framework Interoperability Group" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to php-fig+u...@googlegroups.com.
> To post to this group, send email to php...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/php-fig/9bac3a10-0687-4acb-a595-89d1c43f9e0e%40googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.

[Larry Garfield]

What's the equivalent convention in JavaDoc, Doxygen, etc? Do they use
@type, @var, or something else?

--Larry Garfield

[Jennifer Hodgdon]

Here's a quick survey of how to document class variables in various
existing documentation tools.

Doxygen: uses @var

PHPDoc: uses @var, and you can have or omit the $variable_name

JavaDoc: Does not need or use anything to indicate the type of a
member variable. The declaration of the member variable itself must
have the type, so you don't document it in the JavaDoc.

JSDoc uses @type to document the type of anything you can document.
Syntax is just "@type (type)".

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal web sites and custom Drupal modules

[Mike van Riel]

An important point to note is that @var is only used/intended for class
properties in
both Doxygen and phpDocumentor; which is one of the reasons PSR-5
introduces
@type as a successor to @var.

Also: RDoc/YARD uses @param to document properties.

[Pádraic Brady]

Seems perfectly reasonable to deprecate this. Anyone remember using var in PHP recently? To any recent PHP users of the past decade it may be completely unknown even.

Paddy

Pádraic Brady
http://blog.astrumfutura.com

> To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/529CBF42.9090009%40gmail.com.

[Andreas Hennings (donquixote)]

Some thoughts.

Sorry if this is completely ignorant, I did not follow most of the PSR-5 discussion.

Btw, i personally use @var not only for object properties but also for local variables, if that helps my IDE with type evaluation.

To me, @var or @param means the variable or property. @type would only specify a type of that property.

@var or @param make sense to be combined with a variable name and a description about the purpose of the variable.

If you use @type, then the description needs a separate @description tag. And I would hate that.

Besides, if the docblock is for multiple properties, then how do we know which of them the @description tag refers to?

--------------

Personal favorite:

  /**

   * @var int

   *   The number of sheds.

   *   Second line of the description.

   */

  protected $nSheds;

  /**

   * @var int $nSheds

   *   The number of sheds.

   * @var int $nCows

   *   The number of cows.

   */

  protected $nSheds, $nCows;

  /**

   * Increase the number of sheds.

   *

   * @param int $increment

   *   Number of additional sheds to purchase.

   */

  function purchaseSheds($increment) {..}

--------------

Semantically ok, but not ideal:

  /**

   * @var int $nSheds

   *   The number of sheds.

   * @var int $nCows

   *   The number of cows.

   */

  protected $nSheds, $nCows;

  /**

   * @type int

   * @description The number of sheds.

   *   Where would a second line of the description go?

   */

  protected $nSheds = 1;

  /**

   * The number of sheds.

   * @type int

   */

  protected $nSheds = 1;

--------------

Semantically nonsense:

  /**

   * @type int $nSheds

   * @description The number of sheds.

   */

  protected $nSheds = 1;

  /**

   * @type int $nSheds

   * @description The number of sheds.

   * @type int $nCows

   * @description The number of cows.

   */

  protected $nSheds, $nCows;

  /**

   * The number of sheds.

   * @type int $nSheds

   * The number of cows.

   * @type int $nCows

   */

  protected $nSheds, $nCows;

This is nonsense because $nSheds is not the type, but the variable/property.

  

----------------

What I could imagine is to replace @var by something more fitting for an object property. But I would not see it as a big improvement. @property would make sense semantically, but it already has a different meaning (if used in the class docblock).

  /**

   * @property int

   *   The number of sheds.

   */

  protected $nSheds;

If you are worried about constants, why not use the same syntax but with @const?

  /**

   * @const int

   *   The number of sheds.

   *   Since a recent change of mind this number is constant.

   */

  const N_SHEDS = 1;

[Mike van Riel]

Hello Andreas,

With @var you indicate the type of a specific property and, as I see it,
can provide information regarding the type of the property, such as
whether it has a character limitations. Often the @var description is
used in place of the summary or description of the element itself;
semantically sub-optimal but understandable (I do it too ;)).

I see no purpose in adding an @description tag as a property has got
multiple means of adding a description already:

```
/**
* This is a summary.
*
* This is a description that may
* cover multiple lines and optionally use _Markdown_.
*
* @var int $property may range between 0 and 80.
*/
public $property = 0;
```

If you have multiple properties in one statement and feel the need to
provide a description for each of them then
my take on that would be: split them up into different statements or use
the @type's description
(though I can't really recommend this).

As I see it, you don't need a tag to tell you that the associated
element is a property or constant, because that is
obvious, the intention of the tag is to add information regarding the
type of the value contained in the
subsequent element.

Kind regards,

Mike van Riel

[Andreas Hennings]

2013/12/3 Mike van Riel <draco...@gmail.com>

Hello Andreas,

With @var you indicate the type of a specific property and, as I see it, can provide information regarding the type of the property, such as
whether it has a character limitations. Often the @var description is used in place of the summary or description of the element itself;
semantically sub-optimal but understandable (I do it too ;)).

Is this already documented or agreed upon somewhere, or is this your personal point of view or an observation from what most people do?

(no offense, just asking)

My own post came from looking at the English meaning of "var" and "type" and "param", not from any observation of what others do - if I tried that, it would be very biased anyway, so pointless.

In human language, "var" ("variable") mean the entire thing such as $nCows, whereas "type" only means the type.

From this human language perspective, with "var" or "param" I would expect all information about @nCows to be under this tag.

Using the term "var" only to describe the type conflicts with the human language meaning of "var" or "variable".

Of course if enough people already use it this way, then maybe we should just go with the flow.

 

the intention of the tag is to add information regarding the type of the value contained in the subsequent element.

This is ok for singular property docblocks. For those, an untagged description followed by @type does make sense.

For multiple property docblocks or for local variables, the "subsequent element" is not that clear at all. E.g. if you want a docblock for a variable in a foreach(), then the docblock has to live either before the foreach() or within the loop. Either way, the variable described in the docblock will not be the "subsequent element".

Btw, where would you put the "may range between 0 and 80." on a @param? If the @param also has a description?

If you have multiple properties in one statement and feel the need to provide a description for each of them then [..] use the @type's description (though I can't really recommend this).

And it would conflict with the natural language understanding of "type".

Not that I particularly like multiple properties in one statement.. but having a docblock syntax that *can* be used on multiple properties, without being semantically nonsense, seems like a good thing to ask for.

[Andreas Hennings]

@Mike,

which docblock syntax would you recommend for local variables, e.g. for $name and $plugin in 

  foreach ($plugins as $name => $plugin) {

    ..

  }

Would you use @var or @type? Would you put the docblock within the foreach or outside? How do you distinguish both variables, if they are in the same docblock? Does it allow a type, information regarding the type, and a description about the purpose of the variable?

Does the deprecation of @var apply here, or is this only for properties?

2013/12/3 Andreas Hennings <and...@dqxtech.net>

[Mike van Riel]

On 12/03/2013 01:25 PM, Andreas Hennings wrote:

2013/12/3 Mike van Riel <draco...@gmail.com>

Hello Andreas,

With @var you indicate the type of a specific property and, as I see it, can provide information regarding the type of the property, such as
whether it has a character limitations. Often the @var description is used in place of the summary or description of the element itself;
semantically sub-optimal but understandable (I do it too ;)).

Is this already documented or agreed upon somewhere, or is this your personal point of view or an observation from what most people do?

(no offense, just asking)

(no offense taken)

I find it hard to answer this questions as that paragraph contains multiple assertions, so let me try:

* With @var you indicate the type of a specific property > documented in the @var tag description
* I see it, can provide information regarding the type of the property > My opinion / what I think is the interpretation used in the documentatioon of the original PHPDoc
* Often the @var description is used in place of the summary or description of the element itself > my observation

My own post came from looking at the English meaning of "var" and "type" and "param", not from any observation of what others do - if I tried that, it would be very biased anyway, so pointless.

In human language, "var" ("variable") mean the entire thing such as $nCows, whereas "type" only means the type.

From this human language perspective, with "var" or "param" I would expect all information about @nCows to be under this tag.

Using the term "var" only to describe the type conflicts with the human language meaning of "var" or "variable".

Of course if enough people already use it this way, then maybe we should just go with the flow.

This is exactly why I propose to deprecate `@var`, the semantics is ambiguous and suggests something that is not what is intended.

Btw, where would you put the "may range between 0 and 80." on a @param? If the @param also has a description?

In the description of the @param itself

If you have multiple properties in one statement and feel the need to provide a description for each of them then [..] use the @type's description (though I can't really recommend this).

And it would conflict with the natural language understanding of "type".

I agree; that's why I say that I cannot recommend this ;)

Not that I particularly like multiple properties in one statement.. but having a docblock syntax that *can* be used on multiple properties, without being semantically nonsense, seems like a good thing to ask for.

I do not see what is wrong with using the description or summary to describe groups of properties. If each property deserves a different description I would really want to stimulate people to
separate the properties into different statements.

[Mike van Riel]

On 12/03/2013 01:31 PM, Andreas Hennings wrote:
> @Mike,
> which docblock syntax would you recommend for local variables, e.g.
> for $name and $plugin in
>
> foreach ($plugins as $name => $plugin) {
> ..
> }
>
> Would you use @var or @type? Would you put the docblock within the
> foreach or outside? How do you distinguish both variables, if they are
> in the same docblock? Does it allow a type, information regarding the
> type, and a description about the purpose of the variable?
> Does the deprecation of @var apply here, or is this only for properties?

The original purpose of `@var` was purely for properties (as described
in the original documentation), it has become practice to use @var also
for the situation that you describe but this is semantically incorrect.
This is exactly why I propose to move to `@type`, to remove the ambiguity.

So my proposal would be:

```
/**
* @type string $name
* @type Plugin $plugin
*/

foreach ($plugins as $name => $plugin) {
..
}

```

DocBlocks should always precede a definition; so in this case before the
foreach.

Please note that at this time PSR-5 does not describe this situation;
this is something which still needs to be added.

[Andreas Hennings]

2013/12/3 Mike van Riel <draco...@gmail.com>

On 12/03/2013 01:31 PM, Andreas Hennings wrote:

@Mike,
which docblock syntax would you recommend for local variables, e.g. for $name and $plugin in

  foreach ($plugins as $name => $plugin) {
    ..
  }

Would you use @var or @type? Would you put the docblock within the foreach or outside? How do you distinguish both variables, if they are in the same docblock? Does it allow a type, information regarding the type, and a description about the purpose of the variable?
Does the deprecation of @var apply here, or is this only for properties?

The original purpose of `@var` was purely for properties (as described in the original documentation), it has become practice to use @var also for the situation that you describe but this is semantically incorrect. This is exactly why I propose to move to `@type`, to remove the ambiguity.

What is "semantically"? From a natural language perspective, "var" just means "variable", which does make total sense for local variables.

It we were to reinvent everything, with no regard to PHPDoc, @var would be the perfect fit for everything.

 

So my proposal would be:

```
/**
 * @type string $name
 * @type Plugin $plugin
 */

foreach ($plugins as $name => $plugin) {
    ..
}

```

And where do we put the description, if we want one?

/**

 * The name is the key that was used to register the plugin.

 * Every plugin can put additional stuff on the sandwich.

 * @type string $name

 * @type Plugin $plugin

 */

-> not clear which variable each description refers to.

/**

 * @type string $name

 *   The key that was used to register the plugin.

 * @type Plugin $plugin

 *   Can put additional stuff on the sandwich.

 */

-> Using @type for description stuff, which is not really type-related information.

/**

 * @var string $name

 *   The key that was used to register the plugin.

 * @var Plugin $plugin

 *   Can put additional stuff on the sandwich.

 */

-> this would make total sense, except it is not mentioned in PHPDoc. And it would be totally 1:1 with @param.

(Having the description on a separate line is a personal preference, inspired from Drupal.)

[Mike van Riel]

Interesting viewpoint; I am going to let that sik in and wait for other people's input.
Interested to see what others think

On 12/03/2013 02:17 PM, Andreas Hennings wrote:

[John Flatness]

I'm a supporter of @type as a successor to @var that better describes what it

actually does and has a name that logically applies to variables, properties, and

constants.

The problem of what to do when you're describing two variables or whatever in the same

block is a thorny one, but its something that PHPDoc in general is just not well

equipped for.

Pretty much all the tags, with the possible exception of the "new" @type

or @var, are defined with the assumption that their mere presence within a particular

docblock is enough to associate them with the right element. The short and long

descriptions work the same way. Which element on the following line should the

description, @api, @deprecated, or @since apply to if there's more than one?

"All of them" is the only answer to that question I can really come up with. The 

functionality for supporting multiple variables in a single block is basically a kludge.

(Note a related problem: the similarly-kludgy @property and @method seemingly can't

be described with those kinds of tags at all.)

The "inline PHPDoc" idea as currently included in the spec at section 7 is a potential

solution to these kinds of issues, but it strikes me as a pretty new and unsettled

syntax.

[Andreas Hennings]

2013/12/4 John Flatness <jo...@zerocrates.org>

I'm a supporter of @type as a successor to @var that better describes what it

actually does and has a name that logically applies to variables, properties, and

constants.

The problem of what to do when you're describing two variables or whatever in the same

block is a thorny one, but its something that PHPDoc in general is just not well

equipped for.

It does work perfectly well for @param, which is always multiple variables in the same block.

I personally use @var in the same way as @param on multiple var blocks (especially for local variables), it looks nice and phpStorm likes it too. What is it that makes variables more scary than parameters?

[John Flatness]

I could be way out to lunch here, but I see parameters as a very different situation.

With @param, there's still just one element you're describing: the method or function. It has

several parts of course, the return type and the various parameters, but you're still

fundamentally describing one function. @param just has to worry about defining the type 

and an optional description for one parameter. There's no ambiguity with what to do with

the short and long description of that block, or the other tags: they're all describing the

function.

[Matthieu Napoli]

PSR-2 4.2 specifies that:

There MUST NOT be more than one property declared per statement.

So unless I'm missing something, PSR-5 should focus on PSR-2 compatible code, i.e. one docblock applies to one property.

[Mike van Riel]

I disagree, my opinion is that there should be no relationship or as little possible between PSRs. Also, I want PSR-5 to focus on syntax; not coding standards. Coding standards are in my opinion definitely out of scope for this PSR.

With that, sometimes it is necessary to concede that some things are not possible, our should be solved on the implementor's side, when using a specific coding construct.

As I see it, multiple properties in one declaration is fine. You can use multiple @type tags to define additional information for each property and the summary and description to provide details on that group of properties.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/9cba0cb2-d234-4f0f-8e8d-32e9353207ce%40googlegroups.com.

[Donald Gilbert]

On Monday, December 2, 2013 10:53:18 AM UTC-6, Matthieu Napoli wrote:

Do we really want to have to re-write every property docblock just because "@type" makes more sense?

There is zero impact on existing code. You don't *have* to be PSR-5 compliant in your doc blocks.

PHP-FIG isn't about keeping BC wherever possible - this is not PHP core where we have to keep array_* param ordering because it was done like that so long ago when people weren't thinking (hindsight being 20/20).

We pursue recommended practices and do things that make sense, and it makes sense (to me at least) to call this @type, due to the way I see it used the majority of the time. (Which is typically documenting a class property, and then providing it's type along with it)

[Jennifer Hodgdon]

On 12/05/2013 12:51 PM, Donald Gilbert wrote:
> There is zero impact on existing code. You don't *have* to be PSR-5
> compliant in your doc blocks.

But what is the point of a standard that people cannot or will not adopt?

--Jennifer

[Donald Gilbert]

That's a straw man. Along those lines, I would ask you what is the use of a standard if it's only codifying what people already do? There's a give and take, you see.

If you have issues with complying with the standard based solely on this, I'll gladly run the sed one-liner required to change all your @var to @type.

I don't mean for this discussion to sound trite, but it's a relatively minor change that is very simple to comply with (in the grand scheme of things), and it makes infinitely more since (in my opinion) to use @type instead of @var. It's the evolution of the language.

[guilher...@gmail.com]

-1 from Doctrine.

Changing to @type cannot work as we already have annotations that use @Type.

This cannot be supported on annotations library and a huge issue for many libraries. =(

[]s,

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/9b2ec1a6-fe0d-41a6-9674-80003c714883%40googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
Guilherme Blanco
MSN: guilher...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

[Mike van Riel]

Guilherme,

For this reason there is a clause in PSR-5 that deals with conflicts.

All tags, and thus annotations, provided by third parties should be namespaced, or prefixed with a vendor string and hyphen, in order to comply with PSR-5.

It is impossible to prevent conflicts with all the annotations that are out there, and as such the only option that remains its to require all tags outside of PSR-5 to be namespaced.

For doctrine this is simple as doctrine is able to resolve namespaces aliases and as such you can use an alias to prefix the tag.

Kind regards,

Mike

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAFp73Xvj2dc4aH6WgdwPEmPF5_9hhAtrqGpDvfADnUMYj54pMA%40mail.gmail.com.

[Matthieu Napoli]

Mike,

It's not really practical because as of today, annotations are often used without alias. That would mean changing a lot of existing code, and that would also mean that annotations will be much less practical. Having to import a namespace and alias it, then prefix an annotation with a namespace, it's not the same as just typing an annotation, have it autocompleted and auto-imported by the IDE.

The more I think about it, the more I think @type is a problem. What I'm really surprised about is that this @type tag seems to come out of nowhere, and while I completely agree with the fact that it's better than @var, I'm just really worried of introducing something new into a standard, especially since it's a widely used tag and it means:

- people will have to learn it (I can already imagine loads of "WTF why? @var works perfectly and I'm used to it")

- people will have to rewrite their code

- tools will have to change (IDEs, …)

You could say the same for the rest of the PSR, but here we are talking of changing one of the most used tag after @param maybe.

(and please no more "but you don't have to be PSR-5 compatible", can we at least suppose that we will want to use it, we are in the FIG mailing list)

I think this decision could hurt this PSR and its adoption, a bit like tabs vs spaces in PSR-2. There's not enough gain.

And like it has been said in the discussions for a PSR for a ContainerInterface, a standard should be based on experience. We have no experience using this @type tag. And even though it seems really trivial, we can see it's not really, because in this thread valid concerns have already been raised (@type != @var in that it describes just the type, so where should the description go?).

(hope this post doesn't sound agressive, it's not my intention but I have trouble finding the correct wordings)

Matthieu

[Tom Oram]

I like @type :-)

[Paul M. Jones]

On Dec 6, 2013, at 12:09 AM, guilher...@gmail.com wrote:

> -1 from Doctrine.
>
> Changing to @type cannot work as we already have annotations that use @Type.
> This cannot be supported on annotations library and a huge issue for many libraries. =(

I am conflicted on this point. I get that the Doctrine folk have done tons of work with annotations, including being the first major users of them in a large project.

We saw something like this during the Date class debacle a few years ago. The PHP core folk put together a Date class, but the name turned out to conflict with a widely used PEAR Date library. It was resolved in favor of PEAR keeping rights to Date, and the core PHP class was renamed to DateTime.

I recall thinking back then that the problem stemmed from PEAR not properly namespacing. If all PEAR classes had been prefixed with PEAR_*, instead of claiming the global namespace for themselves, then the name PEAR_Date would never have been in conflict with Date.

I think the same thing is happening with @type. If Doctrine had had the foresight to namespace their annotations, instead of claiming a global space for themselves, there'd be no problem now. (I will grant that it can be difficult to have that kind of foresight; PEAR had that trouble as well.)

Further, it may be difficult to use something *other* than @type for PHPDoc, because if Doctrine is allowed to veto @type on basis of "first use", then we need to check Doctrine for all their annotation names, as well as any other project that uses custom annotation names.

Do we want that to be the operating principle here? I don't know. At this point I have no solution; I am only thinking out loud.


--
Paul M. Jones
pmjo...@gmail.com
http://paul-m-jones.com

[Jennifer Hodgdon]

On 12/06/2013 08:43 AM, Paul M. Jones wrote:
>
> On Dec 6, 2013, at 12:09 AM, guilher...@gmail.com wrote:
>
>> -1 from Doctrine.
>>
>> Changing to @type cannot work as we already have annotations that use @Type.
>> This cannot be supported on annotations library and a huge issue for many libraries. =(
>

> I am conflicted on this point. ... If Doctrine had had the foresight to namespace their annotations...

Yeah, but... The real problem here, IMO, is that PSR-5 is proposing to
invent completely new documentation tags where there is no real
reason, aside from "ooooh, doesn't this seem like it would be beautiful".

Sorry, I'm sounding like a broken record, saying this same thing over
and over again... But I really don't get it. If PSR-5's objective is
to be beautiful, then by all means, make up as many new tags as you
like and it will be lovely and pure and semantically clean, but no one
will want to adopt it because it conflicts with standards in the rest
of the industry, existing code, Doctrine, etc. If PSR-5's objective is
to be a practical standard that tool projects and code projects can
actually use, then be practical and drop @type in favor of @var, and
make sure the other tags and standards are compliant with what people
already think are the best practices.

[Mike van Riel]

On 12/06/2013 06:07 PM, Jennifer Hodgdon wrote:

Yeah, but... The real problem here, IMO, is that PSR-5 is proposing to invent completely new documentation tags where there is no real reason, aside from "ooooh, doesn't this seem like it would be beautiful".

Sorry, I'm sounding like a broken record, saying this same thing over and over again... But I really don't get it. If PSR-5's objective is to be beautiful, then by all means, make up as many new tags as you like and it will be lovely and pure and semantically clean, but no one will want to adopt it because it conflicts with standards in the rest of the industry, existing code, Doctrine, etc. If PSR-5's objective is to be a practical standard that tool projects and code projects can actually use, then be practical and drop @type in favor of @var, and make sure the other tags and standards are compliant with what people already think are the best practices.

Jennifer,

I can only interpret your tone as being condescending with regards to my, and those of others who I consult, intentions and efforts to formalize the PHPDoc Standard and update it with those features missing from it. Feel free to disagree, that is your right as a human being, but please do so with respect.

With regards to you remark:

I have provided several reasons why I believe @var should be deprecated in favor of another tag, which was named @type in this draft, as the original tag does not cover several use-cases:

- constants
- variables
- associative arrays
- compound properties

@var was created and described for single property declarations, please see the original doc on it ( http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.var.pkg.html).

Now, to allow the above there are 2 options:

- Redefine @var to support the use cases above, or
- Introduce a new tag that supercedes @var and covers the use cases above.

For this draft we, myself and the people I consult, have chosen to introduce a new tag as this is a new
iteration of the PHPDoc Standard (so in fact a version 2) and allows us to introduce BC breaks in order
to fix mistakes in the past. By deprecating @var instead of removing it we even try our best to keep BC.

One of the other reasons for naming the tag @type is because of associative array declarations: another
new syntax for describing associative (option) arrays is the following:

/**
 * @type array {
 *     @type integer $field1
 *     @type string $field2
 * }
 */

As I see it @var would be an even worse match here:

/**
 * @var array {
 *     @var integer $field1
 *     @var string $field2
 * }
 */

So yes, we could have introduced another new tag here in addition to @var but why define a new tag that is
basically identical in format and intention to an existing tag? So instead we choose to combine those in one
tag and give it a generic name so that it is useful in different situations.

With kind regards,

Mike van Riel

[Jennifer Hodgdon]

On 12/06/2013 09:35 AM, Mike van Riel wrote:
> Jennifer,
>
> I can only interpret your tone as being condescending with regards to
> my, and those of others who I consult, intentions and efforts to
> formalize the PHPDoc Standard and update it with those features
> missing from it. Feel free to disagree, that is your right as a human
> being, but please do so with respect.

I sincerely apologize for the unintended condescending tone of my
previous remarks. I see how they could have been interpreted that way.

I'll shut up now.

[Mike van Riel]

On 12/06/2013 06:48 PM, Jennifer Hodgdon wrote:
> On 12/06/2013 09:35 AM, Mike van Riel wrote:
>> Jennifer,
>>
>> I can only interpret your tone as being condescending with regards to
>> my, and those of others who I consult, intentions and efforts to
>> formalize the PHPDoc Standard and update it with those features
>> missing from it. Feel free to disagree, that is your right as a human
>> being, but please do so with respect.
>
> I sincerely apologize for the unintended condescending tone of my
> previous remarks. I see how they could have been interpreted that way.
>
> I'll shut up now.
> Jennifer
>

These things happen in a discussion; as long as that can be discussed as
well there is no harm done.

And believe it or not; I would like to ask you to continue to comment
where you feel necessary. A critical note can only help to improve this PSR.
I know I cannot please everybody but food for thought is never bad.

[Donald Gilbert]

To All - please drop the "we've always done it this way, so why add anything new, lets just codify what everyone already does" argument. It's not helpful at all, and it is against everything this group stands for. If we're not going to introduce new things and move people upwards an onwards in development, why are we even using PHP 5? Let's all go back to procedural code because OO is "new to me, and my procedural code works just fine".

It's a straw man argument at best. Please, argue your point based on the merits (or lack thereof) of the proposal itself.

I'll say it again, if you're only issue is that you have to go in and replace @var in your existing code, I'll gladly run the sed one-liner required to do it for you.

*Hugs*

Don

[Mike van Riel]

Matthieu,

Do not worry, I did not find your text aggressive.

Naming conflicts between annotation users and PHPDoc will always be an issue, regardless of @type.

That two annotation providers did not clash earlier is fortunate but is in my opinion also a coincidence. So the standard needs a way to deal with conflicts. The easiest way is to namespace your annotations as most providers already provide that ability.

My alternate suggestion would be to allow non-namespaced annotations but name someone, which I think would be the PHPDoc standard, as being authoritative. That would still mean that where annotation providers and the PHPDoc Standard conflict that the PHPDoc Standard's interpretation is leading. (simply put: annotation providers can change behaviour, PHPDoc cannot after being approved).

If you think there are other ways to resolve a naming conflict, please do suggest it. It is not my intention to make things more difficult but I feel that such things should be described in the PSR.

With regards to @type, it does not necessarily come out of nowhere, it has been discussed between me, Chuck Burgess and several contributors.
Also: @var is not replaced by @type but a new tag @type is introduced and @var is deprecated. This means that people do not have to change their property DocBlocks to be compliant but can start using the new tag with properties, constants and variables from this PSR on.

And tools will have to change after this PSR anyway due to the new syntax that is being introduced to cover the new features; so I don't think that is a showstopper in this case.

You mentioned that the meaning of the description for @type and @var differ and there I disagree; property docblocks have always had a summary, description and @var description; nothing changes there. This PSR describes existing practices and adds missing features. The only way we can base this on existing experiences is by delaying this PSR, codify it in phpDocumentor, wait 2 years until it is adopted and then retry this PSR.

Is this better than what I am attempting now?

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/6cceef86-0f73-4a3e-8ad6-bfc854a35b00%40googlegroups.com.

[Matthieu Napoli]

My alternate suggestion would be to allow non-namespaced annotations but name someone, which I think would be the PHPDoc standard, as being authoritative. That would still mean that where annotation providers and the PHPDoc Standard conflict that the PHPDoc Standard's interpretation is leading. (simply put: annotation providers can change behaviour, PHPDoc cannot after being approved).

If you think there are other ways to resolve a naming conflict, please do suggest it. It is not my intention to make things more difficult but I feel that such things should be described in the PSR.

I agree with this, i.e. if I understood correctly, the PHPDoc standard claims the tags it defines in this PSR, and annotation drivers must not use these tags. Alternatively, annotations can be namespaced and thus all conflicts are avoided (we can even say it's the recommended way). That makes sense to me as it's the way it implicitly works today.

To be honest, I'd love to see annotations use another notation than "@XXX" (or even introduce them in the language :/), that would solve these problems. That could be a future PSR (along with projects that do implement the standard of course ;) ). But until then, I don't see namespacing annotations as the ultimate solution because it's very unpractical, so I'd rather have a big BC break that improves things, rather than one that makes our work more complicated.

With regards to @type, it does not necessarily come out of nowhere, it has been discussed between me, Chuck Burgess and several contributors.
Also: @var is not replaced by @type but a new tag @type is introduced and @var is deprecated. This means that people do not have to change their property DocBlocks to be compliant but can start using the new tag with properties, constants and variables from this PSR on.

And tools will have to change after this PSR anyway due to the new syntax that is being introduced to cover the new features; so I don't think that is a showstopper in this case.

Nothing new to add about this, I understand your stance.

 

You mentioned that the meaning of the description for @type and @var differ and there I disagree; property docblocks have always had a summary, description and @var description; nothing changes there. This PSR describes existing practices and adds missing features. The only way we can base this on existing experiences is by delaying this PSR, codify it in phpDocumentor, wait 2 years until it is adopted and then retry this PSR.

Is this better than what I am attempting now?

Trying new features in the wild before standardizing them, definitely (IMO). Delaying the PSR, definitely not ;).

Cheers.

Matthieu

[Moisa Teodor]

At this point I'm wondering if it wouldn't be better to first standardize on annotations in general - a PSR to define:

 - annotations syntax

 - basic/core annotations (not namespaced)

Otherwise, there will always be somebody to claim a specific annotation. If @type (and it's syntax and parameters) was defined in some other PSR, then Doctrine, phpDoc or any other library could safely use it - without stepping on somebody else's toes.

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/91936fad-f8ce-4631-a64b-5dcc5f71cde3%40googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
Doru Moisa
web: http;//moisadoru.wordpress.com
tel: +40 720 861 922
Bucharest, Romania