Fix and clarify documentation of ref-update and commit-received hooks

- Clarify behavior of ref-update when multiple commits are pushed, i.e.
  that it is only called once for the entire ref update.

- Fix the documentation of commit-received which states that it is called
  for changes pushed for review. In fact it is also called for direct
  pushes, but unlike ref-update it is called once for each commit.

Change-Id: Ie3e2dcab37eeb5d0ed06e05322e72d3fc73925fd

src/main/resources/Documentation/hooks.md

diff --git a/src/main/resources/Documentation/hooks.md b/src/main/resources/Documentation/hooks.md
index c4b5fd7..dad750f 100644
--- a/src/main/resources/Documentation/hooks.md
+++ b/src/main/resources/Documentation/hooks.md
@@ -15,6 +15,10 @@
 ref deletion) is received by Gerrit. It allows a request to be rejected before it
 is committed to the Gerrit repository.
 
+When multiple commits are pushed by direct push, this hook is called once with
+the `--oldrev` being the sha1 of the current branch tip, and `--newrev` being the
+sha1 of the commit that will be the new tip of the branch.
+
 If the hook exits with non-zero return code the update will be rejected and any
 output will be returned to the user.
 
@@ -24,8 +28,10 @@
 
 ### commit-received
 
-This is called when a commit is received for review by Gerrit. It allows a push to
-be rejected before the review is created.
+This is called when a commit is received by Gerrit either by direct push or by
+push for review (to `refs/for/branch`). It allows a push to be rejected before
+a review is created, or before the branch is updated in case of a direct push.
+It is called once for each commit in the push.
 
 If the hook exits with non-zero return code the push will be rejected. Any output
 from the hook will be returned to the user, regardless of the return code.