DocBlock Reflection not returning correct tags

[danez]

Currently when using reflection on a phpDoc the tags returned are not as expected. For example for an @return tag i expect Zend\Code\Generator\DocBlock\Tag\ReturnTag to be returned, but instead Zend\Code\Generator\DocBlock\Tag is always returned (which is missing the types-property from the reflection tag).

When working on a fix i encountered, that the whole generator tags topic does not work with reflection at all. e.g. AuthorTag throws an Exception about undefined function. And the nameing inside the Zend\Code\Generator\DocBlock\Tag* is completely off.

I would like to do a little rewrite, without breaking BC:

• New renamed properties and getter and setters in Author-, License-, Return-, ParamTag (with BC except Author which is completely broken)
• Make fromReflection() deprecated from these classes (in favor of TagManager)
• Add new classes for other Tags similar to the Reflection namespace
• Move Zend\Code\Generator\DocBlock\Tag to class GenericTag
• Create a TagManager similar to Reflection namespace (these class decides which class to create)
• Change DocBlockGenerator to use TagManager
• Create Tests for new TagClasses and TagManager

What do you think about that?

[danez]

I tried to maintain backward compatibility were I could, the only exceptions are:

• Zend\Code\Generator\DocBlock\Tag\AuthorTag: removed set/getDatatype() and set/getParamName()
• Zend\Code\Generator\DocBlock\Tag\AuthorTag: __construct changed from ($options = array()) to ($authorName = null, $authorEmail = null)
• Zend\Code\Generator\DocBlock\Tag\LicenseTag: __construct changed from ($options = array()) to ($url = null, $licenseName = null)
• Zend\Code\Generator\DocBlock\Tag\ReturnTag: __construct changed from ($options = array()) to ($types = array(), $description = null)
• Zend\Code\Generator\DocBlock\Tag\ParamTag: __construct changed from ($options = array()) to ($variableName = null, $types = array(), $description = null)
• Using DocBlockGenerator::fromReflection() and afterwards getTags() is now returning the new Tag classes (ReturnTag, AuthorTag, ParamTag, ...) where applicable and otherwise GenericTag. The deprecated class Tag will not be returned anymore.

[Maks3w]

May you can move the implode(...) part to the parent class in some method like typesToString

[Maks3w]

@danez The PR conflicts with some code in master. Can you rebase it?

[Maks3w]

@ralphschindler May you want to review this.

[danez]

Rebased on master and moved the imploding to abstract class.

[danez]

I think I tested all the new parts and should be ready for review

[Maks3w]

Could you add class docblocks to all new classes describing and explaining the purpose of the class?

[samsonasik]

remove @Package

[danez]

I added class descriptions, all other classes + namespace are selfexplanatory.
According to the comments on the headers I removed @Package from all file headers in the test files.
Also I removed @category, @Package, @subpackage, @license and @copyright from class comments in the test files.

[danez]

The deprecated comments may need some version in them, but I'm not sure what to put there. 2.2.x? 2.3.0?

[weierophinney]

The deprecated comments may need some version in them, but I'm not sure what to put there. 2.2.x? 2.3.0?

2.3.0 -- this is a substantial change, so I'll target it for the next minor version. That said, the bits I saw were mostly BC, and the bits that weren't really didn't matter as you are not expected to create new instances manually for docblock tags (they should be created as part of reflection on their parents!).

Add the deprecation comments, and I'll do final review -- and thanks!

[danez]

Sometimes you might do and instantiate tags when generating code without reflection. But yeah most of the time you do not.
All the BC changes are up in the first comment.

[weierophinney]

Merged to develop for release with 2.3.0.

[danez]

thanks