#180 Add documentation

senzing-garage · Aug 23, 2024 · 889c9a8 · 889c9a8
1 parent 66c7531
commit 889c9a8
Show file tree

Hide file tree

Showing 27 changed files with 293 additions and 210 deletions.
diff --git a/README.md b/README.md
@@ -57,21 +57,21 @@ interface include:
 [Development]: docs/development.md
 [Errors]: docs/errors.md
 [Examples]: docs/examples.md
-[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/template-go.svg
-[Go Report Card Badge]: https://goreportcard.com/badge/github.com/senzing-garage/template-go
-[Go Report Card]: https://goreportcard.com/report/github.com/senzing-garage/template-go
+[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/sz-sdk-go-grpc.svg
+[Go Report Card Badge]: https://goreportcard.com/badge/github.com/senzing-garage/sz-sdk-go-grpc
+[Go Report Card]: https://goreportcard.com/report/github.com/senzing-garage/sz-sdk-go-grpc
 [go-sdk-abstract-factory]: https://github.com/senzing-garage/go-sdk-abstract-factory
-[go-test-darwin.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-darwin.yaml/badge.svg
-[go-test-darwin.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-darwin.yaml
-[go-test-linux.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-linux.yaml/badge.svg
-[go-test-linux.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-linux.yaml
-[go-test-windows.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-windows.yaml/badge.svg
-[go-test-windows.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/go-test-windows.yaml
+[go-test-darwin.yaml Badge]: https://github.com/senzing-garage/sz-sdk-go-grpc/actions/workflows/go-test-darwin.yaml/badge.svg
+[go-test-darwin.yaml]: https://github.com/senzing-garage/sz-sdk-go-grpc/actions/workflows/go-test-darwin.yaml
+[go-test-linux.yaml Badge]: https://github.com/senzing-garage/sz-sdk-go-grpc/actions/workflows/go-test-linux.yaml/badge.svg
+[go-test-linux.yaml]: https://github.com/senzing-garage/sz-sdk-go-grpc/actions/workflows/go-test-linux.yaml
+[go-test-windows.yaml Badge]: https://github.com/senzing-garage/sz-sdk-go-grpc/actions/workflows/go-test-windows.yaml/badge.svg
+[go-test-windows.yaml]: https://github.com/senzing-garage/sz-sdk-go-grpc/actions/workflows/go-test-windows.yaml
 [Go]: https://go.dev/
-[golangci-lint.yaml Badge]: https://github.com/senzing-garage/template-go/actions/workflows/golangci-lint.yaml/badge.svg
-[golangci-lint.yaml]: https://github.com/senzing-garage/template-go/actions/workflows/golangci-lint.yaml
+[golangci-lint.yaml Badge]: https://github.com/senzing-garage/sz-sdk-go-grpc/actions/workflows/golangci-lint.yaml/badge.svg
+[golangci-lint.yaml]: https://github.com/senzing-garage/sz-sdk-go-grpc/actions/workflows/golangci-lint.yaml
 [License Badge]: https://img.shields.io/badge/License-Apache2-brightgreen.svg
-[License]: https://github.com/senzing-garage/template-go/blob/main/LICENSE
+[License]: https://github.com/senzing-garage/sz-sdk-go-grpc/blob/main/LICENSE
 [Package reference]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go-core
 [Senzing Garage]: https://github.com/senzing-garage
 [Senzing gRPC server]: https://github.com/senzing-garage/servegrpc

diff --git a/doc.go b/doc.go
@@ -1,5 +1,5 @@
 /*
-Module sz-sdk-go-grpc communicate over a network using gRPC to the Senzing's C-based library.
+Module sz-sdk-go-grpc communicates over a network using gRPC to the Senzing's C-based library.
 
 # Overview
 

diff --git a/docs/development.md b/docs/development.md
@@ -61,7 +61,7 @@ These are "one-time tasks" which may already have been completed.
     make lint
 
     ```
-    
+
 ## Test
 
 1. Run tests.
@@ -118,16 +118,15 @@ Example:
     make clean
 
     ```
-    
+
 ## References
 
 [clone-repository]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/clone-repository.md
 [docker]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/docker.md
 [git]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/git.md
-[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/template-go.svg
-[Go Reference]: https://pkg.go.dev/github.com/senzing-garage/template-go
+[Go Reference Badge]: https://pkg.go.dev/badge/github.com/senzing-garage/sz-sdk-go-grpc.svg
+[Go Reference]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go-grpc
 [go]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/go.md
-[How to Install Senzing for Go Development]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/install-senzing-for-go-development.md
-[localhost:6060]: http://localhost:6060/pkg/github.com/senzing-garage/template-go/
+[localhost:6060]: http://localhost:6060/pkg/github.com/senzing-garage/sz-sdk-go-grpc/
 [make]: https://github.com/senzing-garage/knowledge-base/blob/main/WHATIS/make.md
 [testcoverage.yaml]: ../.github/coverage/testcoverage.yaml
diff --git a/helper/doc.go b/helper/doc.go
@@ -1,4 +1,4 @@
 /*
-The helper package has miscellaneous function that can be used by the szxxxxxxxx packages.
+Package helper is not intended for public use.
 */
 package helper
diff --git a/helper/getenv.go b/helper/getenv.go
@@ -2,6 +2,17 @@ package helper
 
 import "os"
 
+/*
+The GetEnv function returns the value of an OS environment variable.
+If the environment variable does not exist, the default value is returned.
+
+Input
+  - variableName: The OS environment variable name.
+  - defaultValue: A value to return if the variableName does not exist in the environment.
+
+Output
+  - The actual or defaulted value of the OS environment variable.
+*/
 func GetEnv(variableName string, defaultValue string) string {
 	osenvValue := os.Getenv(variableName)
 	if len(osenvValue) > 0 {

diff --git a/helper/logging.go b/helper/logging.go
@@ -6,6 +6,21 @@ import (
 	"github.com/senzing-garage/go-logging/logging"
 )
 
+/*
+The GetLogger function returns a logger that logs "SZSDKcccceeee" messages.
+
+Input
+  - componentID: The 4-digit identifier of the component used as "nnnn" in the "SZSDKcccceeee" message identifier.
+  - idMessages: A map of error identifiers to error strings.
+  - callerSkip: Default number of "frames" to ascend. See [runtime.Caller].
+  - options: Zero or more Option* types from [logging].
+
+Output
+  - A configured logger.
+
+[logging]: http://localhost:6060/pkg/github.com/senzing-garage/go-logging/logging/
+[runtime.Caller]: https://pkg.go.dev/runtime#Caller
+*/
 func GetLogger(componentID int, idMessages map[int]string, callerSkip int, options ...interface{}) logging.Logging {
 	optionMessageID := fmt.Sprintf("%s%04d", MessageIDPrefix, componentID) + "%04d"
 	loggerOptions := []interface{}{

diff --git a/helper/main.go b/helper/main.go
@@ -4,6 +4,9 @@ package helper
 // Constants
 // ----------------------------------------------------------------------------
 
+/*
+MessageIDPrefix is the message prefix for `SZSDKcccceeee` message identifers where "cccc" is the component ID and "eeee" is the error identifier.
+*/
 const (
 	MessageIDPrefix = "SZSDK"
 )
diff --git a/szabstractfactory/doc.go b/szabstractfactory/doc.go
@@ -1,4 +1,7 @@
 /*
-The szabstractfactory package implements an Abstract Factory Pattern for Sz object creation.
+Package szabstractfactory implements an Abstract Factory Pattern for Sz object creation.
+The [Abstract Factory Pattern] ensures common settings across all created objects.
+
+[Abstract Factory Pattern]: https://en.wikipedia.org/wiki/Abstract_factory_pattern
 */
 package szabstractfactory
diff --git a/szabstractfactory/main.go b/szabstractfactory/main.go
@@ -4,5 +4,8 @@ package szabstractfactory
 // Constants
 // ----------------------------------------------------------------------------
 
-// Identfier of the szabstractfactory package found messages having the format "senzing-6020xxxx".
+/*
+ComponentID is the identifier of the szabstractfactory package.
+abstractfactory package messages will have the format "SZSDK6020eeee" where "eeee" is the error identifier.
+*/
 const ComponentID = 6020
diff --git a/szabstractfactory/szabstractfactory.go b/szabstractfactory/szabstractfactory.go
@@ -17,7 +17,11 @@ import (
 	"google.golang.org/grpc"
 )
 
-// Szabstractfactory is an implementation of the senzing.SzAbstractFactory interface.
+/*
+Szabstractfactory is an implementation of the [senzing.SzAbstractFactory] interface.
+
+[senzing.SzAbstractFactory]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-go/senzing#SzAbstractFactory
+*/
 type Szabstractfactory struct {
 	GrpcConnection *grpc.ClientConn
 }
@@ -27,15 +31,14 @@ type Szabstractfactory struct {
 // ----------------------------------------------------------------------------
 
 /*
-TODO: Write description for CreateSzConfig
-The CreateSzConfig method...
+The CreateSzConfig method returns an SzConfig object
+implemented to use the Senzing native C binary, libSz.so.
 
 Input
   - ctx: A context to control lifecycle.
 
 Output
-  - An senzing.SzConfig object.
-    See the example output.
+  - An SzConfig object.
 */
 func (factory *Szabstractfactory) CreateSzConfig(ctx context.Context) (senzing.SzConfig, error) {
 	_ = ctx
@@ -46,15 +49,14 @@ func (factory *Szabstractfactory) CreateSzConfig(ctx context.Context) (senzing.S
 }
 
 /*
-TODO: Write description for CreateSzConfigManager
-The CreateSzConfigManager method...
+The CreateSzConfigManager method returns an SzConfigManager object
+implemented to use the Senzing native C binary, libSz.so.
 
 Input
   - ctx: A context to control lifecycle.
 
 Output
-  - An senzing.CreateConfigManager object.
-    See the example output.
+  - An SzConfigManager object.
 */
 func (factory *Szabstractfactory) CreateSzConfigManager(ctx context.Context) (senzing.SzConfigManager, error) {
 	_ = ctx
@@ -65,15 +67,14 @@ func (factory *Szabstractfactory) CreateSzConfigManager(ctx context.Context) (se
 }
 
 /*
-TODO: Write description for CreateSzDiagnostic
-The CreateSzDiagnostic method...
+The CreateSzDiagnostic method returns an SzDiagnostic object
+implemented to use the Senzing native C binary, libSz.so.
 
 Input
   - ctx: A context to control lifecycle.
 
 Output
-  - An senzing.SzDiagnostic object.
-    See the example output.
+  - An SzDiagnostic object.
 */
 func (factory *Szabstractfactory) CreateSzDiagnostic(ctx context.Context) (senzing.SzDiagnostic, error) {
 	_ = ctx
@@ -84,15 +85,14 @@ func (factory *Szabstractfactory) CreateSzDiagnostic(ctx context.Context) (senzi
 }
 
 /*
-TODO: Write description for CreateSzEngine
-The CreateSzEngine method...
+The CreateSzEngine method returns an SzEngine object
+implemented to use the Senzing native C binary, libSz.so.
 
 Input
   - ctx: A context to control lifecycle.
 
 Output
-  - An senzing.SzEngine object.
-    See the example output.
+  - An SzEngine object.
 */
 func (factory *Szabstractfactory) CreateSzEngine(ctx context.Context) (senzing.SzEngine, error) {
 	_ = ctx
@@ -103,15 +103,14 @@ func (factory *Szabstractfactory) CreateSzEngine(ctx context.Context) (senzing.S
 }
 
 /*
-TODO: Write description for CreateSzProduct
-The CreateSzProduct method...
+The CreateSzProduct method returns an SzProduct object
+implemented to use the Senzing native C binary, libSz.so.
 
 Input
   - ctx: A context to control lifecycle.
 
 Output
-  - An senzing.SzProduct object.
-    See the example output.
+  - An SzProduct object.
 */
 func (factory *Szabstractfactory) CreateSzProduct(ctx context.Context) (senzing.SzProduct, error) {
 	_ = ctx

diff --git a/szconfig/doc.go b/szconfig/doc.go
@@ -1,5 +1,5 @@
 /*
-The szconfig package is used make szConfig requests to a Senzing gRPC server.
+Package szconfig is used to modify the in-memory representation of a Senzing configuration.
 The gRPC definitions are at https://github.com/senzing-garage/sz-sdk-proto.
 The Senzing gRPC server is at https://github.com/senzing-garage/serve-grpc.
 */

diff --git a/szconfig/main.go b/szconfig/main.go
@@ -4,5 +4,8 @@ package szconfig
 // Constants
 // ----------------------------------------------------------------------------
 
-// Identfier of the szconfig package found messages having the format "senzing-6021xxxx".
-const ComponentID = 6021
+/*
+ComponentID is the identifier of the szconfig package.
+szconfig package messages will have the format "SZSDK6021eeee" where "eeee" is the error identifier.
+*/
+*/const ComponentID = 6021