#104 Update documentation

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning].
 
 ### Changed in 0.5.1
 
+-
+
 ## [0.5.0] - 2024-08-20
 
 ### Changed in 0.5.0

checker/checker_examples_test.go

@@ -9,12 +9,6 @@ import (
 	"github.com/senzing-garage/go-databasing/connector"
 )
 
-func printErr(err error) {
-	if err != nil {
-		fmt.Println(err)
-	}
-}
-
 // ----------------------------------------------------------------------------
 // Examples for godoc documentation
 // ----------------------------------------------------------------------------
@@ -23,11 +17,11 @@ func ExampleBasicChecker_IsSchemaInstalled() {
 	// For more information, visit https://github.com/senzing-garage/go-databasing/blob/main/checker/checker_examples_test.go
 	ctx := context.TODO()
 	databaseConnector, err := connector.NewConnector(ctx, sqliteDatabaseURL)
-	printErr(err)
-	testObject := &BasicChecker{
+	failOnError(err)
+	myChecker := &BasicChecker{
 		DatabaseConnector: databaseConnector,
 	}
-	isSchemaInstalled, _ := testObject.IsSchemaInstalled(ctx)
+	isSchemaInstalled, _ := myChecker.IsSchemaInstalled(ctx)
 	fmt.Printf("isSchemaInstalled: %t", isSchemaInstalled)
 	// Output: isSchemaInstalled: false
 }
@@ -36,11 +30,21 @@ func ExampleBasicChecker_RecordCount() {
 	// For more information, visit https://github.com/senzing-garage/go-databasing/blob/main/checker/checker_examples_test.go
 	ctx := context.TODO()
 	databaseConnector, err := connector.NewConnector(ctx, sqliteDatabaseURL)
-	printErr(err)
-	testObject := &BasicChecker{
+	failOnError(err)
+	myChecker := &BasicChecker{
 		DatabaseConnector: databaseConnector,
 	}
-	recordCount, err := testObject.RecordCount(ctx)
-	printErr(err)
+	recordCount, err := myChecker.RecordCount(ctx)
+	failOnError(err)
 	_ = recordCount // Faux use of recordCount
 }
+
+// ----------------------------------------------------------------------------
+// Internal methods
+// ----------------------------------------------------------------------------
+
+func failOnError(err error) {
+	if err != nil {
+		fmt.Println(err)
+	}
+}

connector/connector_examples_test.go

@@ -7,22 +7,36 @@ import (
 	"fmt"
 )
 
-func printErr(err error) {
-	if err != nil {
-		fmt.Println(err)
-	}
-}
-
 // ----------------------------------------------------------------------------
 // Examples for godoc documentation
 // ----------------------------------------------------------------------------
 
 func ExampleNewConnector_sqlite() {
-	// For more information, visit https://github.com/senzing-garage/go-databasing/blob/main/connectorpostgresql/connectorpostgresql_examples_test.go
+	// For more information, visit https://github.com/senzing-garage/go-databasing/blob/main/connector/connector_examples_test.go
 	ctx := context.TODO()
 	databaseURL := "sqlite3://na:na@$/tmp/sqlite/G2C.db"
 	databaseConnector, err := NewConnector(ctx, databaseURL)
-	printErr(err)
+	failOnError(err)
 	_ = databaseConnector // Faux use of databaseConnector
 	// Output:
 }
+
+func ExampleNewConnector_postgresql() {
+	// For more information, visit https://github.com/senzing-garage/go-databasing/blob/main/connector/connector_examples_test.go
+	ctx := context.TODO()
+	databaseURL := "postgresql://postgres:postgres@localhost/G2/?sslmode=disable"
+	databaseConnector, err := NewConnector(ctx, databaseURL)
+	failOnError(err)
+	_ = databaseConnector // Faux use of databaseConnector
+	// Output:
+}
+
+// ----------------------------------------------------------------------------
+// Internal methods
+// ----------------------------------------------------------------------------
+
+func failOnError(err error) {
+	if err != nil {
+		fmt.Println(err)
+	}
+}

connector/doc.go

@@ -1,4 +1,6 @@
 /*
-Package connector returns a "database/sql/driver.Connector" for a given database URL.
+Package connector returns a [database/sql/driver.Connector] for a given database URL.
+
+[database/sql/driver.Connector]: https://pkg.go.dev/database/sql/driver#Connector
 */
 package connector

connectormssql/connectormssql.go

@@ -12,12 +12,15 @@ import (
 // ----------------------------------------------------------------------------
 
 /*
-Function NewConnector is a wrapper for [Microsoft's MSSQL connector].
+Function NewConnector is a wrapper for [Microsoft's MS-SQL connector].
 
 Input
-  - configuration: See [microsoft/go-mssqldb].
+  - dsn: See [microsoft/go-mssqldb].
 
-[Microsoft's MSSQL connector]: https://pkg.go.dev/github.com/microsoft/go-mssqldb#NewConnector
+Output
+  - [driver.Connector] configured for MS-SQL.
+
+[Microsoft's MS-SQL connector]: https://pkg.go.dev/github.com/microsoft/go-mssqldb#NewConnector
 [microsoft/go-mssqldb]: https://github.com/microsoft/go-mssqldb
 */
 func NewConnector(ctx context.Context, dsn string) (driver.Connector, error) {

connectormssql/connectormssql_examples_test.go

@@ -5,22 +5,28 @@ import (
 	"fmt"
 )
 
+// ----------------------------------------------------------------------------
+// Examples for godoc documentation
+// ----------------------------------------------------------------------------
+
 func ExampleNewConnector() {
 	// For more information, visit https://github.com/senzing-garage/go-databasing/blob/main/connectormssql/connectormssql_examples_test.go
 	ctx := context.TODO()
 	// See https://github.com/microsoft/go-mssqldb#connection-parameters-and-dsn
 	configuration := "user id=sa;password=Passw0rd;database=master;server=localhost"
 	databaseConnector, err := NewConnector(ctx, configuration)
-	printErr(err)
+	failOnError(err)
 	_ = databaseConnector // Faux use of databaseConnector
 	// Output:
 }
 
+func ExampleNewConnector_null() {} // Hack to format godoc documentation examples properly
+
 // ----------------------------------------------------------------------------
-// non-public functions
+// Internal methods
 // ----------------------------------------------------------------------------
 
-func printErr(err error) {
+func failOnError(err error) {
 	if err != nil {
 		fmt.Println(err)
 	}

connectormysql/connectormysql.go

@@ -12,10 +12,16 @@ import (
 // ----------------------------------------------------------------------------
 
 /*
-Wrapper for https://pkg.go.dev/github.com/go-sql-driver/mysql#NewConnector
+Function NewConnector is a wrapper for [go-sql-driver/mysql].
 
 Input
-  - configuration: See https://github.com/go-sql-driver/mysql#dsn-data-source-name
+  - configuration: See [DSN (Data Source Name)].
+
+Output
+  - [driver.Connector] configured for MySQL.
+
+[DSN (Data Source Name)]: https://github.com/go-sql-driver/mysql#dsn-data-source-name
+[go-sql-driver/mysql]: https://pkg.go.dev/github.com/go-sql-driver/mysql#NewConnector
 */
 func NewConnector(ctx context.Context, configuration *mysql.Config) (driver.Connector, error) {
 	_ = ctx

connectormysql/connectormysql_examples_test.go

@@ -9,12 +9,6 @@ import (
 	"github.com/go-sql-driver/mysql"
 )
 
-func printErr(err error) {
-	if err != nil {
-		fmt.Println(err)
-	}
-}
-
 // ----------------------------------------------------------------------------
 // Examples for godoc documentation
 // ----------------------------------------------------------------------------
@@ -32,7 +26,19 @@ func ExampleNewConnector() {
 		DBName:    "G2",
 	}
 	databaseConnector, err := NewConnector(ctx, configuration)
-	printErr(err)
+	failOnError(err)
 	_ = databaseConnector // Faux use of databaseConnector
 	// Output:
 }
+
+func ExampleNewConnector_null() {} // Hack to format godoc documentation examples properly
+
+// ----------------------------------------------------------------------------
+// Internal methods
+// ----------------------------------------------------------------------------
+
+func failOnError(err error) {
+	if err != nil {
+		fmt.Println(err)
+	}
+}

connectormysql/doc.go

@@ -1,4 +1,7 @@
 /*
-Package connectormysql has ready-made "database/sql/driver.Connector" for "github.com/go-sql-driver/mysql".
+Package connectormysql has ready-made [database/sql/driver.Connector] for [github.com/go-sql-driver/mysql].
+
+[database/sql/driver.Connector]: https://pkg.go.dev/database/sql/driver#Connector
+[github.com/go-sql-driver/mysql]: https://github.com/go-sql-driver/mysql
 */
 package connectormysql

connectorpostgresql/connectorpostgresql.go

@@ -12,10 +12,16 @@ import (
 // ----------------------------------------------------------------------------
 
 /*
-Wrapper for https://pkg.go.dev/github.com/lib/pq#NewConnector
+Function NewConnector is a wrapper for [github.com/lib/pq].
 
 Input
-  - dsn: See https://pkg.go.dev/github.com/lib/pq#hdr-Connection_String_Parameters
+  - dsn: See [Connection String Parameters].
+
+Output
+  - [driver.Connector] configured for PostgreSQL.
+
+[github.com/lib/pq]: https://pkg.go.dev/github.com/lib/pq#NewConnector
+[Connection String Parameters]: https://pkg.go.dev/github.com/lib/pq#hdr-Connection_String_Parameters
 */
 func NewConnector(ctx context.Context, dsn string) (driver.Connector, error) {
 	_ = ctx

connectorpostgresql/connectorpostgresql_examples_test.go

@@ -5,12 +5,6 @@ import (
 	"fmt"
 )
 
-func printErr(err error) {
-	if err != nil {
-		fmt.Println(err)
-	}
-}
-
 // ----------------------------------------------------------------------------
 // Examples for godoc documentation
 // ----------------------------------------------------------------------------
@@ -21,7 +15,19 @@ func ExampleNewConnector() {
 	// See https://pkg.go.dev/github.com/lib/pq#hdr-Connection_String_Parameters
 	configuration := "user=postgres password=postgres dbname=G2 host=localhost sslmode=disable"
 	databaseConnector, err := NewConnector(ctx, configuration)
-	printErr(err)
+	failOnError(err)
 	_ = databaseConnector // Faux use of databaseConnector
 	// Output:
 }
+
+func ExampleNewConnector_null() {} // Hack to format godoc documentation examples properly
+
+// ----------------------------------------------------------------------------
+// Internal methods
+// ----------------------------------------------------------------------------
+
+func failOnError(err error) {
+	if err != nil {
+		fmt.Println(err)
+	}
+}

connectorpostgresql/doc.go

@@ -1,4 +1,7 @@
 /*
-Package connectorpostgresql has ready-made "database/sql/driver.Connector" for "github.com/lib/pq".
+Package connectorpostgresql has ready-made [database/sql/driver.Connector] for [github.com/lib/pq].
+
+[github.com/lib/pq]: https://github.com/lib/pq
+[database/sql/driver.Connector]: https://pkg.go.dev/database/sql/driver#Connector
 */
 package connectorpostgresql

connectorsqlite/connectorsqlite.go

@@ -11,13 +11,13 @@ import (
 // Types
 // ----------------------------------------------------------------------------
 
-// Connector represents a fixed configuration for the pq driver with a given
-// name. Connector satisfies the database/sql/driver Connector interface and
-// can be used to create any number of DB Conn's via the database/sql OpenDB
-// function.
-//
-// See https://golang.org/pkg/database/sql/driver/#Connector.
-// See https://golang.org/pkg/database/sql/#OpenDB.
+/*
+Type Sqlite struct implements [driver.Connnector] interface.
+This allows Sqlite to be used with [OpenDB].
+
+[driver.Connnector]: https://golang.org/pkg/database/sql/driver/#Connector
+[OpenDB]: https://golang.org/pkg/database/sql/#OpenDB
+*/
 type Sqlite struct {
 	Filename string
 }
@@ -26,13 +26,21 @@ type Sqlite struct {
 // Interface methods
 // ----------------------------------------------------------------------------
 
-// Connect returns a connection to the database using the fixed configuration
-// of this Connector. Context is not used.
+/*
+Method Connect implements [driver.Connector]'s Connect method.
+Context is not used.
+
+[driver.Connector]: https://golang.org/pkg/database/sql/driver/#Connector
+*/
 func (connector *Sqlite) Connect(_ context.Context) (driver.Conn, error) {
 	return connector.Driver().Open(connector.Filename)
 }
 
-// Driver returns the underlying driver of this Connector.
+/*
+Method Driver implements [driver.Connector]'s Driver method.
+
+[driver.Connector]: https://golang.org/pkg/database/sql/driver/#Connector
+*/
 func (connector *Sqlite) Driver() driver.Driver {
 	return &sqlite.SQLiteDriver{}
 }
@@ -41,6 +49,18 @@ func (connector *Sqlite) Driver() driver.Driver {
 // Constructor methods
 // ----------------------------------------------------------------------------
 
+/*
+Function NewConnector is a wrapper for [github.com/mattn/go-sqlite3].
+
+Input
+  - filename: See [github.com/mattn/go-sqlite3].
+
+Output
+  - [driver.Connector] configured for SQLite.
+
+[github.com/mattn/go-sqlite3]: https://github.com/mattn/go-sqlite3
+[driver.Connector]: https://golang.org/pkg/database/sql/driver/#Connector
+*/
 func NewConnector(ctx context.Context, filename string) (driver.Connector, error) {
 	_ = ctx
 	return &Sqlite{

connectorsqlite/connectorsqlite_examples_test.go

@@ -5,12 +5,6 @@ import (
 	"fmt"
 )
 
-func printErr(err error) {
-	if err != nil {
-		fmt.Println(err)
-	}
-}
-
 // ----------------------------------------------------------------------------
 // Examples for godoc documentation
 // ----------------------------------------------------------------------------
@@ -20,7 +14,19 @@ func ExampleNewConnector() {
 	ctx := context.TODO()
 	configuration := "/tmp/sqlite/G2C.db"
 	databaseConnector, err := NewConnector(ctx, configuration)
-	printErr(err)
+	failOnError(err)
 	_ = databaseConnector // Faux use of databaseConnector
 	// Output:
 }
+
+func ExampleNewConnector_null() {} // Hack to format godoc documentation examples properly
+
+// ----------------------------------------------------------------------------
+// Internal methods
+// ----------------------------------------------------------------------------
+
+func failOnError(err error) {
+	if err != nil {
+		fmt.Println(err)
+	}
+}

connectorsqlite/doc.go

@@ -1,4 +1,7 @@
 /*
-Package connectorsqlite has ready-made "database/sql/driver.Connector" for "github.com/mattn/go-sqlite3".
+Package connectorsqlite has ready-made [database/sql/driver.Connector] for [github.com/mattn/go-sqlite3].
+
+[database/sql/driver.Connector]: https://pkg.go.dev/database/sql/driver#Connector
+[github.com/mattn/go-sqlite3]: https://github.com/mattn/go-sqlite3
 */
 package connectorsqlite