Explain in /projects/ REST API when the "parent" field is "?-N"

Update the documentation for the /projects/ REST API to
incorporate details about retrieving project inheritance in a
tree-like format.

If the calling user fails to satisfy any of the following
conditions:

- Parent project is "ACTIVE" or "READ ONLY", and the user has
READ permission to at least one ref.

- Parent project is "HIDDEN", and the user has READ permission
for 'refs/meta/config'.

Then the 'parent' JSON field will be denoted as '?-N' where N
represents the nesting level within the project's tree.

Release-Notes: Explain in /projects/ REST API when the "parent" field is "?-N"
Change-Id: I301ae1e158bf63bba954006c7c8567db1d439434

1 files changed, 14 insertions, 1 deletions

diff --git a/Documentation/rest-api-projects.txt b/Documentation/rest-api-projects.txt
index 413923f4d2..fef0b08225 100644
--- a/Documentation/rest-api-projects.txt
+++ b/Documentation/rest-api-projects.txt
@@ -268,7 +268,20 @@ List all projects that match substring `test/`:
 Tree(t)::
 Get projects inheritance in a tree-like format. This option does
 not work together with the branch option.
-+
+
+[NOTE]
+If the calling user does not meet any of the following criteria:
+
+* The state of the parent project is either "ACTIVE" or "READ ONLY",
+and the calling user has READ permission to at least one ref.
+* The state of the parent project is "HIDDEN" and the calling user
+has READ permission for 'refs/meta/config'.
+
+Then the 'parent' field will be labeled as '?-N', where N represents the
+nesting level within the project's tree structure. In the provided example,
+'All-Projects' corresponds to level 1, 'parent-project' to level 2, and
+'child-project' to level 3.
+
 Get all the projects with tree option:
 +
 .Request