diff --git a/bin/osv/fields.py b/bin/osv/fields.py
index ffb0a87a7db..24bc751c64f 100644
--- a/bin/osv/fields.py
+++ b/bin/osv/fields.py
@@ -246,7 +246,7 @@ class selection(_column):
 
 #
 # Values: (0, 0,  { fields })    create
-#         (1, ID, { fields })    modification
+#         (1, ID, { fields })    update
 #         (2, ID)                remove (delete)
 #         (3, ID)                unlink one (target id or target of relation)
 #         (4, ID)                link
@@ -480,14 +480,16 @@ class one2many(_column):
 
 #
 # Values: (0, 0,  { fields })    create
-#         (1, ID, { fields })    modification
-#         (2, ID)                remove
-#         (3, ID)                unlink
-#         (4, ID)                link
+#         (1, ID, { fields })    update (write fields to ID)
+#         (2, ID)                remove (calls unlink on ID, that will also delete the relationship because of the ondelete)
+#         (3, ID)                unlink (delete the relationship between the two objects but does not delete ID)
+#         (4, ID)                link (add a relationship)
 #         (5, ID)                unlink all
 #         (6, ?, ids)            set a list of links
 #
 class many2many(_column):
+    """
+
     _classic_read = False
     _classic_write = False
     _prefetch = False
diff --git a/bin/osv/orm.py b/bin/osv/orm.py
index 265382407b1..feb10ab47a4 100644
--- a/bin/osv/orm.py
+++ b/bin/osv/orm.py
@@ -3100,11 +3100,27 @@ class orm(orm_template):
 
         vals format for relational field type.
 
-            + many2many field : [(6, 0, list of ids)] (example: [(6, 0, [8, 5, 6, 4])])
+            + many2many field : 
+
+                For write operation on a many2many fields a list of tuple is
+                expected. The folowing tuples are accepted:
+                 (0, 0,  { fields })    create
+                 (1, ID, { fields })    update (write fields to ID)
+                 (2, ID)                remove (calls unlink on ID, that will also delete the relationship because of the ondelete)
+                 (3, ID)                unlink (delete the relationship between the two objects but does not delete ID)
+                 (4, ID)                link (add a relationship)
+                 (5, ID)                unlink all
+                 (6, 0, list of ids)    set a list of links
+
+                Example:
+
+                    [(6, 0, [8, 5, 6, 4])] set the many2many to ids [8, 5, 6, 4]
+
             + one2many field : [(0, 0, dictionary of values)] (example: [(0, 0, {'field_name':field_value, ...})])
             + many2one field : ID of related record
             + reference field :  model name, id (example: 'product.product, 5')
 
+
         """
         readonly = None
         for field in vals.copy():