From 23a878c40ca8ca73d371c561bb4d2730551f3a38 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Sun, 24 Jan 2016 20:19:46 +0100
Subject: Clean up system hooks API documentation

[ci skip]
---
 doc/api/system_hooks.md | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

(limited to 'doc')

diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
index b605f3540f3..dc036d7e27f 100644
--- a/doc/api/system_hooks.md
+++ b/doc/api/system_hooks.md
@@ -1,18 +1,24 @@
 # System hooks
 
-All methods require admin authorization.
+All methods require administrator authorization.
 
 The URL endpoint of the system hooks can also be configured using the UI in
-the admin area under hooks(`/admin/hooks`).
+the admin area under **Hooks** (`/admin/hooks`).
+
+Read more about [system hooks](../system_hooks/system_hooks.md).
 
 ## List system hooks
 
 Get a list of all system hooks.
 
+---
+
 ```
 GET /hooks
 ```
 
+Example request:
+
 ```bash
 curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks
 ```
@@ -31,6 +37,10 @@ Example response:
 
 ## Add new system hook
 
+Add a new system hook.
+
+---
+
 ```
 POST /hooks
 ```
@@ -39,6 +49,8 @@ POST /hooks
 | --------- | ---- | -------- | ----------- |
 | `url` | string | yes | The hook URL |
 
+Example request:
+
 ```bash
 curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/hooks?url=https://gitlab.example.com/hook"
 ```
@@ -65,6 +77,8 @@ GET /hooks/:id
 | --------- | ---- | -------- | ----------- |
 | `id` | integer | yes | The ID of the hook |
 
+Example request:
+
 ```bash
 curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
 ```
@@ -85,8 +99,12 @@ Example response:
 ## Delete system hook
 
 Deletes a system hook. This is an idempotent API function and returns `200 OK`
-even if the hook is not available. If the hook is deleted a JSON object is
-returned.
+even if the hook is not available.
+
+If the hook is deleted, a JSON object is returned. An error is raised if the
+hook is not found.
+
+---
 
 ```
 DELETE /hooks/:id
@@ -96,6 +114,8 @@ DELETE /hooks/:id
 | --------- | ---- | -------- | ----------- |
 | `id` | integer | yes | The ID of the hook |
 
+Example request:
+
 ```bash
 curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2
 ```
-- 
cgit v1.2.1