Py2neo docs : suggestions to improve the documentation

Hi guys

I am learning both CYPHER and py2neo and sometimes I feel that things could be improved in the documentation for this (py2neo http://py2neo.org) particular driver. I made some comments on Slack about it and I was recommended to be more precise or clear in my comments and to post them here. I am going to keep them here in one thread. Whoever is interested please read below. I might chose to keep a list at the top of the topic so you will know what this is about. The suggestions will be posted in the subsequent posts in this thread.

The doc is not clear on what it is return for the Graph.run() method

Here is another example of lack of clarity

Le't say I have two nodes and the below relationship already in the graph
(a: Computer, {name="MyComp"})
(b: Printer {name="MyPrinter)
(a: Computer, {name="MyComp"}) -[CONNECTS_TO]->(b: Printer {name="MyPrinter)

now I need to merge the below with the above
a=Node(a: Computer, {name="MyComp"})
b=Node(b: Monitor {name="MyMonitor)
rel =Relationship( a, "CONNECTS_TO", b)

now merge takes three arguments:
-rel
-primary label
-primary key

"For each node, the merge is carried out by comparing that node with a potential remote equivalent on the basis of a single label and property value"

For each relationship, the merge is carried out by comparing that relationship with a potential remote equivalent on the basis of matching start and end nodes plus relationship type. If no remote match is found, a new relationship is created; if a match is found, the properties of the remote relationship are updated.

We have 2 nodes in the graph (MyComp and MyPrinter) and I am trying to merge MyComp and MyMonitor. The merge needs two args, a label and a property.. Unless found in the graph, a new node is created.

How does merge compare the three nodes involved in this transaction if they have different tags and names and the merge args are just one label, one key.

Here is what I mean:

(a:Device {name:MyComputer}) -[:CONNECTS_TO]->(b:Peripheral {name:'MyPrinter'})

Assume that I want to update the above to
(a:Device {name:MyComputer CPU='x86'}) -[:CONNECTS_TO]->(b:Peripheral {name:'MyNEWPrinter'})

According with the above, py2neo will need two arguments Device, name or Peripheral , name
whichever I chose will create a new node for the other type of device.
if I use merge ( Relationship (a, b CONNECTS_TO), Device, name) when py2neo tries to update the printer it finds that node b does not fit the bill (none of the keys is found) and it will create a new Peripheral with the name MyNEWPinter

Here is the code

db.schema.create_uniqueness_constraint("Computer",'name')
db.schema.create_uniqueness_constraint("Peripheral",'name')

a=Node("Computer", name="MyComputer")
b=Node("Peripheral", name="MyPrinter")
db.create(a)
db.create(b)
db.create(Relationship(a, "CONNECTS_TO", b))
c=Node("Computer", name="MyComputer")
d=Node("Peripheral", name="MyMonitor")
The below line will fail
db.merge(Relationship(c, "CONNECTS_TO", d),"Peripheral","name")

In the above if we replace the last three lines of code with this code, then it works. The issue is that the newly created MyNewPrinter gets both labels, "Computer" and "Peripheral".... which is unexpected and not very clearly documented At least for a beginner like me this makes the things very difficult to understand
c=Node("Computer", name="MyComputer")
d=Node("Peripheral", name="MyMonitor")
Note the change in the last line, using different labels
db.merge(Relationship(c, "CONNECTS_TO", d),'Computer','name')

Here is someone else having similar difficulties

More requests for merge examples here