Document all options of list projects endpoint

Add missing documentation of all the possible options that list
projects endpoint supports.

Change-Id: I30886e35cfdec4bb0944b2951245cb4e863c3fd4

Documentation/rest-api-projects.txt

@@ -52,22 +52,110 @@ by project name.
   }
 ----
 
-.Get all projects with their description
-****
-get::/projects/?d
-****
+[[project-options]]
+==== Project Options
+
+Branch(b)::
+Limit the results to the projects having the specified branch and
+include the sha1 of the branch in the results.
++
+Get projects that have a 'master' branch:
++
+.Request
+----
+GET /projects/?b=master HTTP/1.0
+----
++
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "some-project": {
+      "id": "some-project",
+      "branches": {
+        "master": "c5ed9dfcbf002ca0e432d788dab6ca2387829ca7"
+      }
+    },
+    "some-other-project": {
+      "id": "some-other-project",
+      "branches": {
+        "master": "ef1c270142f9581ecf768f4193fc8f8a81102ec2"
+      }
+    },
+  }
+----
+
+Description(d)::
+Include project description in the results.
++
+Get all the projects with their description:
++
+.Request
+----
+GET /projects/?d HTTP/1.0
+----
++
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "some-project": {
+      "id": "some-project",
+      "description": "Description of some project."
+    },
+    "some-other-project": {
+      "id": "some-other-project",
+       "description": "Description of some other project."
+      }
+    },
+  }
+----
+
+Limit(n)::
+Limit the number of projects to be included in the results.
++
+Query the first project in the project list:
++
+.Request
+----
+  GET /projects/?n=1 HTTP/1.0
+----
++
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "some-project": {
+      "id": "some-project"
+    }
+  }
+----
+
 
 [[suggest-projects]]
-The `/projects/` URL also accepts a prefix string in the `p` parameter.
-This limits the results to those projects that start with the specified
+Prefix(p)::
+Limit the results to those projects that start with the specified
 prefix.
++
 List all projects that start with `platform/`:
-
++
 .Request
 ----
   GET /projects/?p=platform%2F HTTP/1.0
 ----
-
++
 .Response
 ----
   HTTP/1.1 200 OK
@@ -84,22 +172,118 @@ List all projects that start with `platform/`:
     }
   }
 ----
++
 E.g. this feature can be used by suggestion client UI's to limit results.
 
-The `/projects/` URL also accepts a limit integer in the `n` parameter.
-This limits the results to show `n` projects.
-
-Query the first 25 projects in project list.
+Skip(S)::
+Skip the given number of projects from the beginning of the list.
++
+Query the second project in the project list:
++
+.Request
 ----
-  GET /projects/?n=25 HTTP/1.0
+  GET /projects/?n=1&S=1 HTTP/1.0
+----
++
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "some-other-project": {
+      "id": "some-other-project"
+    }
+  }
 ----
 
-The `/projects/` URL also accepts a start integer in the `S` parameter.
-The results will skip `S` projects from project list.
-
-Query 25 projects starting from index 50.
+Substring(m)::
+Limit the results to those projects that match the specified substring.
++
+List all projects that match substring `test/`:
++
+.Request
 ----
-  GET /projects/?n=25&S=50 HTTP/1.0
+  GET /projects/?m=test%2F HTTP/1.0
+----
++
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "test/some-project": {
+      "id": "test%2Fsome-project",
+    },
+    "some-path/test/some-other-project": {
+      "id": "some-path%2Ftest%2Fsome-other-project",
+    }
+  }
+----
+
+Tree(t)::
+Get projects inheritance in a tree-like format. This option does
+not work together with the branch option.
++
+Get all the projects with tree option:
++
+.Request
+----
+GET /projects/?t HTTP/1.0
+----
++
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "All-Projects" {
+      "id": "All-Projects"
+    },
+    "child-project": {
+      "id": "child-project",
+      "parent":"parent-project"
+    },
+    "parent-project": {
+      "id": "parent-project",
+      "parent":"All-Projects"
+    }
+  }
+----
+
+Type(type)::
+Get projects with specified type: ALL, CODE, PERMISSIONS.
++
+Get all the projects of type 'PERMISSIONS':
++
+.Request
+----
+GET /projects/?type=PERMISSIONS HTTP/1.0
+----
++
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "All-Projects" {
+      "id": "All-Projects"
+    },
+    "some-parent-project": {
+      "id": "some-parent-project"
+    }
+  }
 ----
 
 [[get-project]]