Improve setup docs regarding Doctrine ODM

[winterstefan]

Goal:

• Improve setup documentation
• Use equal configuration for ODM as for the ORM

Steps:

• Add user field where necessary (ORM already has them).
• Use Doctrine\ODM\MongoDB\Mapping\Annotations configuration (same as for ORM).
• Remove getClient() and setClient() since the super class already implements getter / setter.

[alcaeus]

👍

[dinamic]

Some prefer XML, other prefer YML. You seem to prefer annotations.

IMO would be best to have as much docs and examples as possible.

P.S Merging master to your branch would make the Travis CI build green.

[alcaeus]

@dinamic See PR description:

Use Doctrine\ODM\MongoDB\Mapping\Annotations configuration (same as for ORM).

As for Doctrine recommendations, we recommend using XML for libraries or when you want to decouple your domain logic from your mapping. In other cases, use annotations.

[dkarlovi]

when you want to decouple your domain logic from your mapping. In other cases,

There shouldn't be "other cases", when do you NOT want to do this?

[alcaeus]

One could argue that even using XML ties your domain logic to your mapping, but that's outside the scope here. I was merely stating the reason for the change.

[dkarlovi]

Well, you obviously need the mapping somewhere, but IMO promoting annotations has done some harm here, it's now seen as a go-to way of doing things even though it shouldn't be.

[alcaeus]

but IMO promoting annotations has done some harm here

In that case, feel free to change the ORM documentation. The primary goal was to have consistent documentation and ensure the ODM documentation produces a working result.

[dkarlovi]

Sorry, didn't mean (just) here, I mean overall in the community.

Annotations should be a quick way to do something short-term, but in the long run you'll end up wanting to have used something else. :)

[alcaeus]

That's subjective - while not optimal I believe annotations provide a nice balance between speed and "clean code feel".

Returning to the topic, what would you suggest for the issue at hand? ODM docs are actually broken and should be fixed. Would you rather drop XML for now and reintroduce it in a docs expansion later or would you rather change ORM docs first?

[dkarlovi]

That's subjective

Exactly why we should follow the established way of having all three in the docs. Is there any way we could do that?

[alcaeus]

all three

Please let's leave out YAML. We're dropping support for YAML in ODM 2.0 and ORM 3.0.

[dkarlovi]

Please let's leave out YAML.

That's 1/3 of work already done! 😆 So we need XML for ORM and annotations for ODM? Seems doable, do you agree?

[alcaeus]

Seems doable, do you agree?

Absolutely. @winterstefan can you make the changes for ODM? I can make the changes for ORM unless you prefer to do them as well 😉

[alcaeus]

@winterstefan still up to work on this PR or would you like someone else to finish up? Note that #558 brings in annotations for ODM, so we could take that part of the docs from there.

[winterstefan]

@alcaeus Sorry, my bad. Actually I'm pretty out of this topic. Would be cool for someone else to finish up.

[alcaeus]

Fair enough, I know just the guy to do it 😉