Refactor namespaces API documentation [ci skip]

Author: axilleas

doc/api/namespaces.md

@@ -1,13 +1,22 @@
 # Namespaces
 
+Namespaces account for usernames and groupnames.
+
+[Pagination](README.md#pagination) is used.
+
 ## List namespaces
 
-Get a list of namespaces. (As user: my namespaces, as admin: all 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 /namespaces
 ```
 
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces
+```
+
 ```json
 [
   {
@@ -23,22 +32,28 @@ GET /namespaces
 ]
 ```
 
-You can search for namespaces by name or path, see below.
-
 ## Search for namespace
 
-Get all namespaces that match your string in their name or path.
+Get all namespaces that match a string in their name or path.
 
 ```
 GET /namespaces?search=foobar
 ```
 
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `search`  | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria |
+
+```bash
+curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces?search=twitter
+```
+
 ```json
 [
   {
-    "id": 1,
-    "path": "user1",
-    "kind": "user"
+    "id": 4,
+    "path": "twitter",
+    "kind": "group"
   }
 ]
 ```