doctrine/annotations — pull request #9 by JonathanO (2013-05-27 14:33:48+00:00)
Title: Workaround PHP compiler globals storing doc_comments

The PHP parser stores the last docblock comment that it saw in a compiler global. When the compiler next sees something that might conceivably have a docblock comment, that thing becomes the owner of the comment, and the global is cleared.
Unfortunately the parser does not clear state between parses. A call to token_get_all() on something containing a docblock comment will cause the global to be set. The next file to be compiled by an include() will start off with that global, and this (under some circumstances) can cause the comment to be erroneously associated with another class.

This workaround ensures that after a call to token_get_all() we reset the parser to a state where the doc_comment compiler global contains an empty comment, and is therefore "safe" for us.

This is only a workaround: With this fix we have to hope that any other uses of token_get_all() in the user's codebase are also similarly protected. IMO this is a PHP bug (for which I shall raise a bug report), and should, long term, be fixed there.