Doctrine offers three ways to define the object mapping properties: in XML, in YAML and as inline docblock annotations in the code. The Doctrine documentation doesn't give any advice on choosing among them, but I'm specifically wondering if there is a generally accepted for best practice with regard to keeping mapping metadata for an ORM system in the file where the objects are defined versus keeping it in a separate data file. Is there?
I don't think so.
The different options are there to satisfy developers' personal preferences. Some people don't like XML, preferring something a bit simpler and more straightforward like YAML. Annotations are a nice way to add ORM capability to code that already exists.
It certainly seems to be in keeping with PHP's philosophy of "There's more than one way to do it, and the more ways the better."