Improve transaction timeout docs (#531)

* Improve transaction timeout docs

The timeout behaves differently on different server versions in respects to
the user being or not being able to overwrite the server timeout with a bigger
value.

Also make sure the docs mention special values like `0`.

* Docs: improve worning around transaction timeout

Signed-off-by: Grant Lodge <6323995+thelonelyvulpes@users.noreply.github.com>

* Fix capitalization

Signed-off-by: Richard Irons <115992270+RichardIrons-neo4j@users.noreply.github.com>

---------

Signed-off-by: Grant Lodge <6323995+thelonelyvulpes@users.noreply.github.com>
Signed-off-by: Richard Irons <115992270+RichardIrons-neo4j@users.noreply.github.com>
Co-authored-by: Stephen Cathcart <stephen.cathcart@neotechnology.com>

neo4j/transaction_config.go

@@ -8,13 +8,13 @@
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- *      https://www.apache.org/licenses/LICENSE-2.0
+ *     https://www.apache.org/licenses/LICENSE-2.0
  *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 
 package neo4j
@@ -33,16 +33,30 @@ type TransactionConfig struct {
 
 // WithTxTimeout returns a transaction configuration function that applies a timeout to a transaction.
 //
+// Transactions that execute longer than the configured timeout will be terminated by the database.
+// This functionality allows user code to limit query/transaction execution time.
+// The specified timeout overrides the default timeout configured in the database using the `db.transaction.timeout`
+// setting (`dbms.transaction.timeout` before Neo4j 5.0).
+// Values higher than `db.transaction.timeout` will be ignored and will fall back to the default for server versions
+// between 4.2 and 5.2 (inclusive).
+// A `0` duration will make the transaction execute indefinitely.
+// `math.MinInt` will use the default timeout configured on the server.
+// Other negative durations are invalid.
+//
 // To apply a transaction timeout to an explicit transaction:
+//
 //	session.BeginTransaction(WithTxTimeout(5*time.Second))
 //
 // To apply a transaction timeout to an auto-commit transaction:
+//
 //	session.Run("RETURN 1", nil, WithTxTimeout(5*time.Second))
 //
 // To apply a transaction timeout to a read transaction function:
+//
 //	session.ExecuteRead(DoWork, WithTxTimeout(5*time.Second))
 //
 // To apply a transaction timeout to a write transaction function:
+//
 //	session.ExecuteWrite(DoWork, WithTxTimeout(5*time.Second))
 func WithTxTimeout(timeout time.Duration) func(*TransactionConfig) {
 	return func(config *TransactionConfig) {
@@ -53,15 +67,19 @@ func WithTxTimeout(timeout time.Duration) func(*TransactionConfig) {
 // WithTxMetadata returns a transaction configuration function that attaches metadata to a transaction.
 //
 // To attach a metadata to an explicit transaction:
+//
 //	session.BeginTransaction(WithTxMetadata(map[string)any{"work-id": 1}))
 //
 // To attach a metadata to an auto-commit transaction:
+//
 //	session.Run("RETURN 1", nil, WithTxMetadata(map[string)any{"work-id": 1}))
 //
 // To attach a metadata to a read transaction function:
+//
 //	session.ExecuteRead(DoWork, WithTxMetadata(map[string)any{"work-id": 1}))
 //
 // To attach a metadata to a write transaction function:
+//
 //	session.ExecuteWrite(DoWork, WithTxMetadata(map[string)any{"work-id": 1}))
 func WithTxMetadata(metadata map[string]any) func(*TransactionConfig) {
 	return func(config *TransactionConfig) {