Show columns clarifications (#1826) (#1842)

Update the column information to not just be in the text but as proper
tables for the 2 show commands that didn't have them as tables already.

Cherry-picked from #1826

Co-authored-by: Therese Magnusson <[email protected]>

Author: renetapopova

modules/ROOT/pages/authentication-authorization/manage-privileges.adoc

@@ -438,11 +438,29 @@ Other users' privileges cannot be listed when using a non-native auth provider.
 
 When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted.
 
-For an easy overview of the existing privileges, it is recommended to use the `AS COMMANDS` version of the `SHOW` command.
-This returns the column `command` of type `STRING` containing the privileges as the commands that are granted or denied.
+For an easy overview of the existing privileges, it is recommended to use the `AS COMMANDS` version of the `SHOW` command, which returns two columns.
 
-When omitting the `AS COMMANDS` clause, results will include multiple columns describing privileges:
+.`SHOW PRIVILEGES AS COMMANDS` output
+[options="header", width="100%", cols="2a,4,2m"]
+|===
+| Column
+| Description
+| Type
+
+| command
+| The privilege as the command that is granted or denied.
+Or in the `AS REVOKE COMMANDS` case, the command to revoke the privilege. label:default-output[]
+| STRING
 
+| immutable
+| Whether or not the privilege is immutable.
+| BOOLEAN
+|===
+
+Alternatively, you can omit the `AS COMMANDS` clause and get the full details of the privileges returned in multiple columns.
+They are all returned by default without requiring a `YIELD`.
+
+.`SHOW PRIVILEGES` output
 [options="header", width="100%", cols="4m,6a,2m"]
 |===
 | Column | Description | Type
@@ -475,8 +493,6 @@ E.g., the entire DBMS, a specific database, a graph, or sub-graph access.
 
 | immutable
 | Whether or not the privilege is immutable.
-
-This column is also available for the `AS COMMAND` variant using `YIELD`.
 | BOOLEAN
 
 | user

modules/ROOT/pages/authentication-authorization/manage-roles.adoc

@@ -131,7 +131,7 @@ Lists the privileges granted to the specified roles.
 
 When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted.
 
-For more information, see xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges].
+The `SHOW ROLE name PRIVILEGES` command is described in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges].
 
 | Required privilege
 a|
@@ -339,9 +339,22 @@ For more information, see xref:authentication-authorization/dbms-administration.
 == Listing roles
 
 
-Available roles can be seen using `SHOW ROLES`.
-This returns a single column `role` of type `STRING`, containing the role name.
+You can view all available roles using the Cypher command `SHOW ROLES`, which returns a single column.
 
+.`SHOW ROLES` output
+[options="header", width="100%", cols="2a,4,2m"]
+|===
+| Column
+| Description
+| Type
+
+| role
+| Role name
+| STRING
+|===
+
+.List all roles
+====
 [source, cypher, role=noplay]
 ----
 SHOW ROLES
@@ -363,6 +376,7 @@ This is the same command as `SHOW ALL ROLES`.
 
 1+a|Rows: 6
 |===
+====
 
 When first starting a Neo4j DBMS, there are a number of built-in roles:
 
@@ -379,9 +393,24 @@ More information about the built-in roles and their privileges can be found in x
 There are multiple versions of this command, the default being `SHOW ALL ROLES`.
 To only show roles that are assigned to users, the command is `SHOW POPULATED ROLES`.
 To see which users are assigned to which roles, `WITH USERS` can be added to the command.
-This will return an additional `STRING` column, `member`, containing the username.
-Since this gives a result with one row for each user, if a role is assigned to two users it will show up twice.
+The command produces a row per role per user and yields the following column in addition to the one output by `SHOW ROLES`:
+
+.`SHOW POPULATED ROLES WITH USERS` output
+[options="header", width="100%", cols="2a,4,2m"]
+|===
+| Column
+| Description
+| Type
 
+| member
+| User name
+| STRING
+|===
+
+Since this gives a result with one row for each user, it shows up twice if a role is assigned to two users.
+
+.Show roles with users
+====
 [source, cypher, role=noplay]
 ----
 SHOW POPULATED ROLES WITH USERS
@@ -415,9 +444,12 @@ The table of results will show information about the role and what database it b
 
 2+a|Rows: 6
 |===
+====
 
-It is also possible to filter and sort the results by using `YIELD`, `ORDER BY` and `WHERE`:
+It is also possible to filter and sort the results by using `YIELD`, `ORDER BY` and `WHERE`.
 
+.Show roles with ordering and filtering
+====
 [source, cypher, role=noplay]
 ----
 SHOW ROLES YIELD role
@@ -443,10 +475,6 @@ It is also possible to use `SKIP` and `LIMIT` to paginate the results.
 
 1+a|Rows: 3
 |===
-
-[NOTE]
-====
-The `SHOW ROLE name PRIVILEGES` command is found in xref:authentication-authorization/manage-privileges.adoc#access-control-list-privileges[Listing privileges].
 ====