Add documentation comments

Author: ali-ince

neo4j/config_resolver.go

@@ -25,12 +25,20 @@ import (
 	"github.com/neo4j-drivers/gobolt"
 )
 
+// ServerAddress represents a host and port. Host can either be an IP address or a DNS name.
+// Both IPv4 and IPv6 hosts are supported.
 type ServerAddress interface {
+	// Hostname returns the host portion of this ServerAddress.
 	Hostname() string
+	// Port returns the port portion of this ServerAddress.
 	Port() string
 }
 
+// ServerAddressResolver is an interface that defines a resolver function used by the routing driver to
+// resolve the initial address used to create the driver.
 type ServerAddressResolver interface {
+	// Resolve resolves the given address to a set of other addresses. If the returned slice is empty, the driver
+	// will continue using the original address.
 	Resolve(address ServerAddress) []ServerAddress
 }
 
@@ -51,6 +59,7 @@ func newServerAddressUrl(hostname string, port string) *url.URL {
 	return &url.URL{Host: hostAndPort}
 }
 
+// A helper function that generates a ServerAddress with provided hostname and port information.
 func NewServerAddress(hostname string, port string) ServerAddress {
 	return newServerAddressUrl(hostname, port)
 }

neo4j/driver.go

@@ -17,6 +17,7 @@
  * limitations under the License.
  */
 
+// Package neo4j provides required functionality to connect and execute statements against a Neo4j Database.
 package neo4j
 
 import (
@@ -45,7 +46,21 @@ type Driver interface {
 	Close() error
 }
 
-// NewDriver is the entry method to the neo4j driver to create an instance of a Driver
+// NewDriver is the entry point to the neo4j driver to create an instance of a Driver. It is the first function to
+// be called in order to establish a connection to a neo4j database. It requires a Bolt URI and an authentication
+// token as parameters and can also take optional configuration function(s) as variadic parameters.
+//
+// In order to connect to a single instance database, you need to pass a URI with scheme 'bolt'
+//	driver, err = NewDriver("bolt://db.server:7687", BasicAuth(username, password))
+//
+// In order to connect to a causal cluster database, you need to pass a URI with scheme 'bolt+routing' and its host
+// part set to be one of the core cluster members.
+//	driver, err = NewDriver("bolt+routing://core.db.server:7687", BasicAuth(username, password))
+//
+// You can override default configuration options by providing a configuration function(s)
+//	driver, err = NewDriver(uri, BasicAuth(username, password), function (config *Config) {
+// 		config.MaxConnectionPoolSize = 10
+// 	})
 func NewDriver(target string, auth AuthToken, configurers ...func(*Config)) (Driver, error) {
 	parsed, err := url.Parse(target)
 	if err != nil {

neo4j/record.go

@@ -22,8 +22,12 @@ package neo4j
 // Record contains ordered keys and values that are returned from a statement executed
 // on the server
 type Record interface {
+	// Keys returns the keys available
 	Keys() []string
+	// Values returns the values
 	Values() []interface{}
+	// Get returns the value (if any) corresponding to the given key
 	Get(key string) (interface{}, bool)
+	// GetByIndex returns the value at given index
 	GetByIndex(index int) interface{}
 }

neo4j/record_impl.go

@@ -21,24 +21,19 @@ package neo4j
 
 import "errors"
 
-// Record contains ordered keys and values that are returned from a statement executed
-// on the server
 type neoRecord struct {
 	keys   []string
 	values []interface{}
 }
 
-// Keys returns the keys available
 func (record *neoRecord) Keys() []string {
 	return record.keys
 }
 
-// Values returns the values
 func (record *neoRecord) Values() []interface{} {
 	return record.values
 }
 
-// Get returns the value (if any) corresponding to the given key
 func (record *neoRecord) Get(key string) (interface{}, bool) {
 	for i := range record.keys {
 		if record.keys[i] == key {
@@ -49,7 +44,6 @@ func (record *neoRecord) Get(key string) (interface{}, bool) {
 	return nil, false
 }
 
-// GetByIndex returns the value at given index
 func (record *neoRecord) GetByIndex(index int) interface{} {
 	if len(record.values) <= index {
 		panic(errors.New("index out of bounds"))

neo4j/result.go

@@ -19,11 +19,19 @@
 
 package neo4j
 
+// Result provides access to the result of the executing statement.
 type Result interface {
+	// Keys returns the keys available on the result set.
 	Keys() ([]string, error)
+	// Next returns true only if there is a record to be processed.
 	Next() bool
+	// Err returns the latest error that caused this Next to return false.
 	Err() error
+	// Record returns the current record.
 	Record() Record
+	// Summary returns the summary information about the statement execution.
 	Summary() (ResultSummary, error)
+	// Consume consumes the entire result and returns the summary information
+	// about the statement execution.
 	Consume() (ResultSummary, error)
 }

neo4j/result_impl.go

@@ -25,7 +25,6 @@ import (
 	"github.com/neo4j-drivers/gobolt"
 )
 
-// Result provides access to the result of the executing statement
 type neoResult struct {
 	keys            []string
 	records         []Record
@@ -96,7 +95,6 @@ func (result *neoResult) collectRecord(fields []interface{}) {
 	}
 }
 
-// Keys returns the keys available on the result set
 func (result *neoResult) Keys() ([]string, error) {
 	for !result.runCompleted {
 		if currentResult, err := result.runner.receive(); currentResult == result && err != nil {
@@ -107,7 +105,6 @@ func (result *neoResult) Keys() ([]string, error) {
 	return result.keys, nil
 }
 
-// Next returns true only if there is a record to be processed
 func (result *neoResult) Next() bool {
 	if result.err != nil {
 		return false
@@ -135,17 +132,14 @@ func (result *neoResult) Next() bool {
 	return result.current != nil
 }
 
-// Err returns the latest error that caused this Next to return false
 func (result *neoResult) Err() error {
 	return result.err
 }
 
-// Record returns the current record
 func (result *neoResult) Record() Record {
 	return result.current
 }
 
-// Summary returns the summary information about the statement execution
 func (result *neoResult) Summary() (ResultSummary, error) {
 	for result.err == nil && !result.resultCompleted {
 		if _, err := result.runner.receive(); err != nil {

neo4j/runner.go

@@ -195,7 +195,7 @@ func (runner *statementRunner) runStatement(statement *neoStatement) (Result, er
 		return nil, err
 	}
 
-	runHandle, err := runner.connection.Run(statement.cypher, &statement.params)
+	runHandle, err := runner.connection.Run(statement.text, &statement.params)
 	if err != nil {
 		defer runner.closeConnection()
 

neo4j/runner_test.go

@@ -57,7 +57,7 @@ var _ = Describe("Runner", func() {
 				mockConnection.EXPECT().Server(),
 			)
 
-			_, err := runner.runStatement(&neoStatement{cypher: "RETURN 1"})
+			_, err := runner.runStatement(&neoStatement{text: "RETURN 1"})
 
 			Expect(err).To(BeNil())
 		})

neo4j/session.go

@@ -19,11 +19,22 @@
 
 package neo4j
 
+// Session represents a logical connection (which is not tied to a physical connection)
+// to the server
 type Session interface {
+	// LastBookmark returns the bookmark received following the last successfully completed transaction.
+	// If no bookmark was received or if this transaction was rolled back, the bookmark value will not be changed.
 	LastBookmark() string
+	// BeginTransaction starts a new explicit transaction on this session
 	BeginTransaction(configurers ...func(*TransactionConfig)) (Transaction, error)
+	// ReadTransaction executes the given unit of work in a AccessModeRead transaction with
+	// retry logic in place
 	ReadTransaction(work TransactionWork, configurers ...func(*TransactionConfig)) (interface{}, error)
+	// WriteTransaction executes the given unit of work in a AccessModeWrite transaction with
+	// retry logic in place
 	WriteTransaction(work TransactionWork, configurers ...func(*TransactionConfig)) (interface{}, error)
+	// Run executes an auto-commit statement and returns a result
 	Run(cypher string, params map[string]interface{}, configurers ...func(*TransactionConfig)) (Result, error)
+	// Close closes any open resources and marks this session as unusable
 	Close() error
 }

neo4j/session_impl.go

@@ -24,8 +24,6 @@ import (
 	"sync/atomic"
 )
 
-// Session represents a logical connection (which is not tied to a physical connection)
-// to the server
 type neoSession struct {
 	driver     *goboltDriver
 	accessMode AccessMode
@@ -119,29 +117,22 @@ func (session *neoSession) LastBookmark() string {
 	return session.lastBookmark
 }
 
-// BeginTransaction starts a new explicit transaction on this session
 func (session *neoSession) BeginTransaction(configurers ...func(*TransactionConfig)) (Transaction, error) {
 	return beginTransactionInternal(session, session.accessMode, configurers...)
 }
 
-// ReadTransaction executes the given unit of work in a AccessModeRead transaction with
-// retry logic in place
 func (session *neoSession) ReadTransaction(work TransactionWork, configurers ...func(*TransactionConfig)) (interface{}, error) {
 	return runTransaction(session, AccessModeRead, work, configurers...)
 }
 
-// WriteTransaction executes the given unit of work in a AccessModeWrite transaction with
-// retry logic in place
 func (session *neoSession) WriteTransaction(work TransactionWork, configurers ...func(*TransactionConfig)) (interface{}, error) {
 	return runTransaction(session, AccessModeWrite, work, configurers...)
 }
 
-// Run executes an auto-commit statement and returns a result
 func (session *neoSession) Run(cypher string, params map[string]interface{}, configurers ...func(*TransactionConfig)) (Result, error) {
-	return runStatementOnSession(session, &neoStatement{cypher: cypher, params: params}, configurers...)
+	return runStatementOnSession(session, &neoStatement{text: cypher, params: params}, configurers...)
 }
 
-// Close closes any open resources and marks this session as unusable
 func (session *neoSession) Close() error {
 	if atomic.CompareAndSwapInt32(&session.open, 1, 0) {
 		if err := closeRunner(session); err != nil {