update associations documentation #21

Merged
merged 3 commits into from Mar 12, 2013

Conversation

Projects
None yet
2 participants
Member

dbu commented Mar 6, 2013

I tried to weight understandability against duplication of the ORM doc here.

+
+.. _collections:
+
+Collections
@dbu

dbu Mar 6, 2013

Member

there was a long arguing about clean domain models. i think linking to the orm doc for that is enough.

+applies that operation to the association, be it single or
+collection valued.
+
+Persistence by Reachability: Cascade Persist
@dbu

dbu Mar 6, 2013

Member

we really follow the same logic in phpcr-odm, right? or is it different?
maybe we should repeat here that children automatically have cascade persist?

en/reference/association-mapping.rst
+- merge : Cascades merge operations to the associated entities.
+- detach : Cascades detach operations to the associated entities.
+- refresh : Also refresh the associated entities when refreshing this entity.
+- translation : Cascade the current translation locale to associated entities.
@dbu

dbu Mar 6, 2013

Member

is the translation cascade case already documented somewhere? whould it go into a section below like persist, or into the multilanguage chapter and just be linked here?

en/reference/association-mapping.rst
+ produce an Exception and rollback the flush() operation.
+3. Collections without new entities are skipped.
+
+This concept is called Persistence by Reachability: New entities
@dantleech

dantleech Mar 6, 2013

Contributor

Should probably be: .... This concept is called persistance by reachability; new entities ....

i.e. emphasis instead of capitilization and a semi-colon. not 100% sure on that, but the capitalized words (mid sentance) look wierd to me.

en/reference/association-mapping.rst
+
+The mixed referrers is a much simpler but read only mapping to get a collection
+of *all* documents that have a reference to this document. The only possible option
+to this mapping is the `referenceType` to only get hard resp. weak references. If
@dantleech

dantleech Mar 6, 2013

Contributor

don't understand this sentance: "... to only get hard resp. weak references."

en/reference/association-mapping.rst
+cascading persist and remove are implicit and can not be disabled. (A
+PHPCR node always must have a parent, removing the parent removes its children.)
+The child removal happens on PHPCR level and does not trigger additional
+lifecycle events.
@dantleech

dantleech Mar 6, 2013

Contributor

.. For Children: Children should be lowercase I think.

.. and can not be disabled. (A ... : paranthesis should be before the full stop, "can not" should be "cannot" and the full stop should be after the paranthesis, again I think :)

and cannot be disabled (a PHPCR node must always have a parent, removing the parent removes its children).
@dbu

dbu Mar 7, 2013

Member

learning something new every day: http://www.dailywritingtips.com/cannot-or-can-not/ - i thought cannot is kind of sloppy and "can not" the correct thing to do :-) will fix it then.

en/reference/association-mapping.rst
+
+The following cascade options exist:
+
+- persist : Cascades persist operations to the associated entities.
@dantleech

dantleech Mar 6, 2013

Contributor
  1. Entities => Documents
  2. In the annotations reference I delimted options with emphasis like
  • persist - Cascade persist operations to the associated entities.

Which I think I copied from the sf docs for stuff like that, e.g. http://symfony.com/doc/current/book/templating.html#template-suffix

I think I have also seen two backquotes being used to delimt the "option" in definition lists like this, but maybe that applies more to class names etc. Is there are style guide that covers stuff like this?

en/reference/association-mapping.rst
+ the cascade operation is about to be performed. This approach allows
+ entity lifecycle events to be performed for each of these operations.
+
+ However, pulling objects graph into memory on cascade can cause considerable performance
@dantleech

dantleech Mar 6, 2013

Contributor

Should be ...

However, pulling the object graph into memory can cause considerable performance overhead - especially .

i.e. pulling the object graph into memory and - instead of comma after overhead.

en/reference/association-mapping.rst
+it will unnecessarily degrade the performance of your application.
+For each cascade operation that gets activated Doctrine also
+applies that operation to the association, be it single or
+collection valued.
@dantleech

dantleech Mar 6, 2013

Contributor

double back-ticks around "cascade-all", e.g. cascade=all ?
should the last sentance be "be it single or multi valued" ?

Member

dbu commented Mar 7, 2013

thanks a lot for the input dantleech. (good thing you don't ride your bicycle at night :-)

quite a bit of this was copied and (insufficiently) adapted from the orm doc. i made sure to have document and not entity everywhere now, and clarified the places where you noted inconsistencies.

dbu added a commit that referenced this pull request Mar 12, 2013

@dbu dbu merged commit a19e99e into master Mar 12, 2013

@dbu dbu deleted the update-associations-doc branch Mar 12, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment