Polish manuals

go-manual/modules/ROOT/pages/bookmarks.adoc

@@ -3,7 +3,7 @@
 When working with a Neo4j cluster, <<causal_consistency>> is enforced by default in most cases, which guarantees that a query is able to read changes made by previous queries.
 The same does not happen by default for multiple xref:transactions.adoc[transactions] running in parallel though.
 In that case, you can use _bookmarks_ to have one transaction wait for the result of another to be propagated across the cluster before running its own work.
-This is not a requirement, and *you should only use bookmarks if you _need_ casual consistency across different transactions*.
+This is not a requirement, and *you should only use bookmarks if you _need_ casual consistency across different transactions*, as waiting for bookmarks can have a negative performance impact.
 
 A _bookmark_ is a token that represents some state of the database.
 By passing one or multiple bookmarks along with a query, the server will make sure that the query does not get executed before the represented state(s) have been established.
@@ -192,7 +192,7 @@ func printFriendships(ctx context.Context, session neo4j.SessionWithContext) (an
 }
 ----
 
-<1> Collect and combine bookmarks from different sessions using `SessionWithContext.LastBookmarks()` and `neo4j.CombineBookmarks()`.
+<1> Collect and combine bookmarks from different sessions using `SessionWithContext.LastBookmarks()` and `neo4j.CombineBookmarks()`, storing them in a link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j#Bookmarks[`Bookmarks`] object.
 <2> Use them to initialize another session with the `Bookmarks` config parameter.
 
 image:{common-image}/driver-passing-bookmarks.svg[]

go-manual/modules/ROOT/pages/concurrency.adoc

@@ -2,7 +2,7 @@
 
 You may leverage link:https://go.dev/tour/concurrency/1[Goroutines and channels] to run concurrent queries, or to delegate the processing of a query's result to multiple threads.
 The examples below also use the Go link:https://pkg.go.dev/sync[`sync` package] to coordinate different routines.
-If you are not familiar with concurrency in Go, checkout link:https://go.dev/blog/pipelines[The Go Programming Language -- Go Concurrency Patterns: Pipelines and cancellation].
+If you are not familiar with concurrency in Go, checkout link:https://go.dev/blog/pipelines[The Go Programming Language -> Go Concurrency Patterns: Pipelines and cancellation].
 
 If you need causal consistency across different transactions, use xref:bookmarks.adoc[bookmarks].
 
@@ -103,7 +103,7 @@ func consumer(wg *sync.WaitGroup, records <-chan *neo4j.Record, log chan string,
 <1> A Goroutine runs the query to the Neo4j server with a xref:transactions.adoc[managed transaction].
 Notice that the driver session is created _inside_ the routine, as sessions are not thread-safe.
 <2> The channel `recordsC` is where the query result records get streamed to.
-The transaction function from `ExecuteWrite()` writes to it, and the various ``consumer``s read from it.
+The transaction function from `.ExecuteWrite()` writes to it, and the various ``consumer``s read from it.
 It is buffered so that the driver does not retrieve records faster than what the consumers can handle.
 <3> Each result record coming from the server is sent over the `recordsC` channel.
 The streaming continues so long as there are records to be processed, after which the channel gets closed and the routine exits.

go-manual/modules/ROOT/pages/connect-advanced.adoc

@@ -90,7 +90,7 @@ defer driver.Close(ctx)
 
 == Further connection parameters
 
-You can find all `DriverWithContext` configuration parameters in the link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/config#Config[API documentation -- config package].
+You can find all `DriverWithContext` configuration parameters in the link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/config#Config[API documentation -> config package].
 
 
 ifndef::backend-pdf[]

go-manual/modules/ROOT/pages/connect.adoc

@@ -2,6 +2,7 @@
 
 Once you have xref:install.adoc#install-driver[installed the driver] and have xref:install.adoc#get-an-instance[a running Neo4j instance], you are ready to connect your application to the database.
 
+
 == Connect to the database
 
 You connect to a Neo4j database by creating a <<DriverWithContext>> object and providing a URL and an authentication token.
@@ -45,18 +46,18 @@ Connection is instead deferred to when the first query is executed.
 The safest practice is to `defer` the call to `DriverWithContext.Close(ctx)` after the object is successfully created.
 Note that there are corner cases in which `.Close()` might return an error, so you may want to catch that as well.
 
-`DriverWithContext` objects are _immutable_, _thread-safe_, and fairly _expensive to create_, so your application should only create one instance.
-If you need to query the database with a different user than the one you created the object with, use xref:query-simple#impersonation[impersonation].
-If you want to alter a `DriverWithContext` configuration, you will need to create a new object.
+**`Driver` objects are immutable, thread-safe, and expensive to create**, so your application should create only one instance and pass it around (you may share `Driver` instances across threads).
+If you need to query the database through several different users, use xref:query-simple#impersonation[impersonation] without creating a new `DriverWithContext` instance.
+If you want to alter a `DriverWithContext` configuration, you need to create a new object.
 
 
 == Connect to an Aura instance
 
-When you create an <<Aura>> instance, you may download a text file containing the connection information to the database.
+When you create an <<Aura>> instance, you may download a text file (a so-called _Dotenv file_) containing the connection information to the database in the form of environment variables.
 The file has a name of the form `Neo4j-a0a2fa1d-Created-2023-11-06.txt`.
 
-To connect to such an instance, you may either use the URI, username, and password explicitly in your application, or load the content of the connection file in the environment with `godotenv.Load()` and populate your local variables via `os.Getenv()`.
-This approach requires the package link:https://pkg.go.dev/github.com/joho/godotenv[`godotenv`].
+You can either  manually extract the URI and the credentials from that file, or use a third party-module to load them.
+We recommend the module package link:https://pkg.go.dev/github.com/joho/godotenv[`godotenv`] for that purpose.
 
 [source, go]
 ----
@@ -95,6 +96,10 @@ func main() {
 }
 ----
 
+[TIP]
+An Aura instance is not conceptually different from any other Neo4j instance, as Aura is simply a _deployment mode_ for Neo4j.
+When interacting with a Neo4j database through the driver, it doesn't make a difference whether it is an Aura instance it is working with or a different deployment.
+
 
 == Further connection parameters
 

go-manual/modules/ROOT/pages/data-types.adoc

@@ -2,6 +2,13 @@
 
 The tables in this section show the mapping between Cypher data types and Go types.
 
+[TIP]
+*When accessing a record's content, all its properties are of type `any`.*
+This means that you have to cast them to the relevant Go type if you want to use methods/features defined on such types.
+For example, if the `name` property coming from the database is a string, `record.AsMap()["name"][1]` would result in an _invalid operation_ error at compilation time.
+For it to work, cast the value to string _before_ using it as a string: `name := record.AsMap()["name"].(string)` and then `name[1]`.
+
+
 == Core types
 
 [options="header"]
@@ -153,7 +160,7 @@ duration := neo4j.Duration{
 fmt.Println(duration)  // 'P1Y2DT3.000000004S'
 ----
 
-For full documentation, see link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/dbtype#Duration[API documentation -- Duration].
+For full documentation, see link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/dbtype#Duration[API documentation -> Duration].
 
 
 == Spatial types
@@ -270,7 +277,7 @@ fmt.Println("Node properties:", node.Props)
 // Node properties: map[name:Alice]
 ----
 
-For full documentation, see link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/dbtype#Node[API documentation -- Node].
+For full documentation, see link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/dbtype#Node[API documentation -> Node].
 
 
 === `Relationship`
@@ -308,7 +315,7 @@ fmt.Println("Relationship end elID:", relationship.EndElementId)
 // Relationship end elID: 4:2691aa68-87cc-467d-9d09-431df9f5c456:1
 ----
 
-For full documentation, see link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/dbtype#Relationship[API documentation -- Relationship].
+For full documentation, see link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/dbtype#Relationship[API documentation -> Relationship].
 
 
 === `Path`
@@ -382,7 +389,7 @@ func addFriend(ctx context.Context, driver neo4j.DriverWithContext, name string,
 
 ----
 
-For full documentation, see link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/dbtype#Path[API documentation -- Path].
+For full documentation, see link:https://pkg.go.dev/github.com/neo4j/neo4j-go-driver/v5/neo4j/dbtype#Path[API documentation -> Path].
 
 
 == Exceptions