From 2b3e64a6015bcb9a2bf365dcab148d5024833d91 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Sun, 24 Jan 2016 19:28:24 +0100
Subject: [PATCH] Clean up namespaces API documentation

[ci skip]
---
 doc/api/namespaces.md | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md
index 68ed8bd3152..42d9ce3d391 100644
--- a/doc/api/namespaces.md
+++ b/doc/api/namespaces.md
@@ -1,22 +1,29 @@
 # Namespaces
 
-Namespaces account for usernames and groupnames.
+Usernames and groupnames fall under a special category called namespaces.
+
+For users and groups supported API calls see the [users](users.md) and
+[groups](groups.md) documentation respectively.
 
 [Pagination](README.md#pagination) is used.
 
 ## List namespaces
 
-Get a list of namespaces. As a user, your namespaces are listed whereas if you
-are an administrator you get a list of all namespaces in the GitLab instance.
+Get a list of the namespaces of the authenticated user. If the user is an
+administrator, a list of all namespaces in the GitLab instance is shown.
 
 ```
 GET /namespaces
 ```
 
+Example request:
+
 ```bash
 curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces
 ```
 
+Example response:
+
 ```json
 [
   {
@@ -44,10 +51,14 @@ GET /namespaces?search=foobar
 | --------- | ---- | -------- | ----------- |
 | `search`  | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria |
 
+Example request:
+
 ```bash
 curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces?search=twitter
 ```
 
+Example response:
+
 ```json
 [
   {