Apply suggestions from code review

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

Author: nadja-muller

modules/ROOT/pages/clauses/use.adoc

@@ -18,31 +18,30 @@ USE <graph reference>
 
 A graph reference can be described using:
 
-* direct graph references: `USE db1`
-* the graph function xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId()`], to access a graph of a given element: `USE graph.byName(<element-id-string>)`
+* Direct graph references: `USE db1`.
+* The graph function xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId()`], to access a graph of a given element: `USE graph.byName(<element-id-string>)`.
 
 When connected to a composite database, a graph reference may additionally be passed with:
 
-* the graph function xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`], which allows the graph reference to be resolved dynamically: `USE graph.byName(<string-expression>)`
+* The graph function xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`], which allows the graph reference to be resolved dynamically: `USE graph.byName(<string-expression>)`.
 
 A more detailed description of how and when a graph references needs to be quoted and/or escaped is defined xref::queries/expressions.adoc#graphreferences[here].
 
 == USE clause when connected to a standard or system database
-=== Allowed graph reference targets
 
-All databases except composite databases can be targeted. It is not possible to target more than one database. This is only possible when connected to a composite database.
+All databases are valid graph reference targets except composite databases.
+Targeting multiple databases is not allowed, unless connected to a composite database.
 
 === Position of use clauses
 When connected to a non-composite database, the `USE` clause can only appear as the prefix of schema commands, or as the first clause of queries. There may be multiple `USE` clauses as long as they target the same database.
 
 == USE clause when connected to a composite database
-=== Allowed graph reference targets
-When executing queries against a composite database, the `USE` clause must only refer to graphs that are part of the current composite database. The constituents can be listed either with `RETURN graph.names()` when connected to the composite database or `SHOW DATABASES YIELD name, constituents RETURN *`.
+When executing queries against a link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[composite database], the `USE` clause must only refer to graphs that are part of the current composite database. The constituents can be listed either with `RETURN graph.names()` when connected to the composite database or `SHOW DATABASES YIELD name, constituents RETURN *`.
 
 === Position of use clauses
-When running queries against a link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[composite database], the `USE` clause can appear as the first clause of:
+When running queries against a composite database, the `USE` clause can appear as the first clause of:
 
-* a query (as when connected to a non-composite database)
+* A query (similar to how it is used when connected to a non-composite database).
 * Union parts:
 +
 [source, syntax, role="noheader"]

modules/ROOT/pages/queries/expressions.adoc

@@ -85,18 +85,22 @@ String literals can contain the following escape sequences:
 
 [[graphreferences]]
 == Graph references
-* static graph references: `USE <symbolic-name>` (for standard and system databases), `USE <symbolic-name>.<symbolic-name>` (for composite databases)
-* dynamic graph reference with the xref:functions/graph.adoc#functions-graph-byname[`graph.byName`] function, to access a graph of a given name: `USE graph.byName(<string-expression>)`
-* dynamic graph reference with the xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId`] function, to access a graph of a given node or relationship: `USE graph.byName(<element-id-string>)`
+* Static graph references: `USE <symbolic-name>` (for link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[standard and system databases]), `USE <symbolic-name>.<symbolic-name>` (for link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/composite-databases/concepts/[composite databases]).
+* Dynamic graph reference with the xref:functions/graph.adoc#functions-graph-byname[`graph.byName`] function, to access a graph of a given name: `USE graph.byName(<string-expression>)`.
+* Dynamic graph references with the xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId`] function, to access a graph of a given node or relationship: `USE graph.byName(<element-id-string>)`.
 
 Rules on string expressions for graph references when using identifiers (static graph references, administration commands) or a string (graph.byName function):
 
 * Unquoted dots are separators between a composite database and its constituent. For example, `composite.db1` represents the constituent composite.db1 in the composite database composite. To refer to a database with a dot in its name, quote the graph reference instead: `+`composite.db1`+`
-* When resolving a graph reference within a graph function, the string argument is parsed the same as a static graph reference before resolving it. This means that for most arguments, `USE graph.byName(<graph-reference>)` is equal to `USE <graph-reference>`. However, escaping rules for xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] are applied to the argument. When passing in a string literal, this means both the escaping rules for xref:queries/expressions.adoc#expressions-string-literals[string literals] (when parsing the query) as well as the escaping rules for xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] (when evaluating the graph reference) are applied. For example, the graph reference in `USE graph.byName('+composite.1\\u0041+')` will resolve to the constituent `composite.1a` of the composite database `composite`.
+* When resolving a graph reference within a graph function,  the string argument is parsed like a static graph reference.
+ Thus, `USE graph.byName(<graph-reference>)` is typically equivalent to `USE <graph-reference>`.
+ However, escaping rules for xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] are applied to the argument.
+ For string literals, both the escaping rules for xref:queries/expressions.adoc#expressions-string-literals[string literals] (during query parsing) and xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] (during graph reference evaluation) are applied.
+For example, the graph reference in `USE graph.byName('+composite.1\\u0041+')` resolves to the constituent `composite.1a` of the composite database `composite`.
 
 Graph references are used within:
 
 * xref:clauses/use.adoc[`USE clauses`]
-* database and alias names when managing databases and aliases, see link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[Database administration]
+* Database and alias names when managing link:{neo4j-docs-base-uri}/operations-manual/current/database-administration/[databases and aliases].