diff --git a/docs/merge.rst b/docs/merge.rst
index 47984a868..413f03480 100644
--- a/docs/merge.rst
+++ b/docs/merge.rst
@@ -6,12 +6,13 @@ Merge
 
 .. automethod:: pygit2.Repository.merge_base
 .. automethod:: pygit2.Repository.merge
+.. automethod:: pygit2.Repository.merge_analysis
 
 The merge method
 =================
 
 The method does a merge over the current working copy.
-It gets an Oid object as a parameter and returns a MergeResult object.
+It gets an Oid object as a parameter.
 
 As its name says, it only does the merge, does not commit nor update the
 branch reference in the case of a fastforward.
@@ -21,17 +22,14 @@ merge with the default ones defined in GIT_MERGE_OPTS_INIT libgit2 constant.
 
 Example::
 
-    >>> branch_head_hex = '5ebeeebb320790caf276b9fc8b24546d63316533'
-    >>> branch_id = self.repo.get(branch_head_hex).id
-    >>> merge_result = self.repo.merge(branch_id)
+    >>> other_branch_tip = '5ebeeebb320790caf276b9fc8b24546d63316533'
+    >>> repo.merge(other_branch_tip)
 
-The MergeResult object
-======================
+You can now inspect the index file for conflicts and get back to the
+user to resolve if there are. Once there are no conflicts left, you
+can create a commit with these two parents.
 
-Represents the result of a merge and contains these fields:
-
-- is_uptodate: bool, if there wasn't any merge because the repo was already
-  up to date
-- is_fastforward: bool, whether the merge was fastforward or not
-- fastforward_id: Oid, in the case it was a fastforward, this is the
-  forwarded id.
+   >>> user = repo.default_signature()
+   >>> tree = repo.index.write_tree()
+   >>> new_commit = repo.create_commit('HEAD', user, user, tree,
+                                       [repo.head.target, other_branch_tip])