[IMP] field.m2m: better doc for auto-named m2m relationships

bzr revid: odo@openerp.com-20111003132653-413c41exoj64q416

openerp/osv/fields.py

@@ -495,6 +495,15 @@ class one2many(_column):
 class many2many(_column):
     """Encapsulates the logic of a many-to-many bidirectional relationship, handling the
        low-level details of the intermediary relationship table transparently.
+       A many-to-many relationship is always symmetrical, and can be declared and accessed
+       from either endpoint model.
+       If ``rel`` (relationship table name), ``id1`` (source foreign key column name)
+       or id2 (destination foreign key column name) are not specified, the system will
+       provide default values. This will by default only allow one single symmetrical
+       many-to-many relationship between the source and destination model.
+       For multiple many-to-many relationship between the same models and for
+       relationships where source and destination models are the same, ``rel``, ``id1``
+       and ``id2`` should be specified explicitly.
 
        :param str obj: destination model
        :param str rel: optional name of the intermediary relationship table. If not specified,