DCOM-207: Add AnnotationReader::getFunctionAnnotations()

[doctrinebot]

Jira issue originally created by user benjamin:

Currently, the annotation reader supports reading annotations on class, method and property.
This could be extended to read annotations on any kind of function, by adding the following methods:

public function getFunctionAnnotations(\ReflectionFunctionAbstract $function);
public function getFunctionAnnotation(\ReflectionFunctionAbstract $function, $annotationName);

This could be done without breaking BC in the following ways:

• Keep the Reader interface as it is
• Add a new interface, for example FullReader, that would extend Reader to add these two methods
• Add the new methods to AnnotationReader, CachedReader, etc.
• Update these classes to implement FullReader; thus they would still implement Reader and stay compatible.

Then, on the next major release (3.0.0), we could:

• Add the two methods to Reader
• Remove FullReader
• Add a note to the UPGRADE file to rename FullReader to Reader in application code.

In case you're wondering why I'm proposing this feature, I'm developing a lightweight framework, which allows any method, function, or closure to be used as a controller.
I can currently parse annotations when using a class method, but cannot provide support for annotations on the others.

That would be a great addition.
I've checked the code, and it looks like the only difficulty would be to parse "use" statements for the file where the function is declared, whereas for now it is always assumed that there is a class, and that the file name will be inferred from there. But as ReflectionFunctionAbstract provides a getFileName() method, it's technically feasible as well.

Let me know what you think!
If you have no objection to the concept, I can start working on a PR for this feature.

[guilhermeblanco]

This issue was moved to doctrine/annotations#83