diff --git a/CHANGELOG.md b/CHANGELOG.md index f9a50b0..09ede20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +## v0.2.1 + +- Bump license year. +- Make public API stable. +- Comment public functions and types. + ## v0.2.0 - Add support for drivers which do not implement `driver.DriverContext`. diff --git a/README.md b/README.md index f8742d7..dec2e6b 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,6 @@ Go implementation of https://google.github.io/sqlcommenter/. -Public API is not stable, expect breaking changes. - ## Usage with pgx stdlib driver ```go diff --git a/attrs.go b/attrs.go index 808602e..688b472 100644 --- a/attrs.go +++ b/attrs.go @@ -4,6 +4,7 @@ import ( "bytes" ) +// AttrPairs builds Attrs from multiple key value pairs. func AttrPairs(pairs ...string) Attrs { if len(pairs)%2 == 1 { panic("got odd number of pairs") @@ -15,13 +16,16 @@ func AttrPairs(pairs ...string) Attrs { return attrs } +// Attr represents attribute with key and value. type Attr struct { Key string Value string } +// Attrs wrap map of attributes. type Attrs map[string]string +// Update updates map from other Attrs. func (a Attrs) Update(other Attrs) { for k, v := range other { a[k] = v diff --git a/comment.go b/comment.go index 4f86dc9..7d4cb14 100644 --- a/comment.go +++ b/comment.go @@ -12,6 +12,7 @@ const ( commentEnd = "*/" ) +// Comment adds comments to query using provided options. func Comment(ctx context.Context, query string, opts ...Option) string { if len(opts) == 0 { return query diff --git a/driver.go b/driver.go index 125b67e..a7c403d 100644 --- a/driver.go +++ b/driver.go @@ -5,6 +5,7 @@ import ( "database/sql/driver" ) +// WrapDriver wraps sql driver with sqlcommenter support. func WrapDriver(drv driver.Driver, opts ...Option) driver.Driver { return &commentDriver{ drv: drv, @@ -28,7 +29,7 @@ func (d *commentDriver) Open(name string) (driver.Conn, error) { func (d *commentDriver) OpenConnector(name string) (driver.Connector, error) { drvCtx, ok := d.drv.(driver.DriverContext) if !ok { - return &dsnConnector{dsn: name, drv: d}, nil + return newDSNConnector(name, d), nil } ctr, err := drvCtx.OpenConnector(name) @@ -62,6 +63,13 @@ func (c *connector) Driver() driver.Driver { return c.drv } +func newDSNConnector(dsn string, drv *commentDriver) *dsnConnector { + return &dsnConnector{ + dsn: dsn, + drv: drv, + } +} + type dsnConnector struct { dsn string drv *commentDriver diff --git a/options.go b/options.go index 6c82d93..22ff064 100644 --- a/options.go +++ b/options.go @@ -4,18 +4,23 @@ import ( "context" ) +// Option configures commenter. type Option func(cmt *commenter) +// AttrProvider provides Attrs from context.Context. type AttrProvider interface { GetAttrs(context.Context) Attrs } +// AttrProviderFunc adapts func to AttrProvider. type AttrProviderFunc func(context.Context) Attrs +// GetAttrs returns Attrs. func (f AttrProviderFunc) GetAttrs(ctx context.Context) Attrs { return f(ctx) } +// WithAttrs configures commenter with Attrs. func WithAttrs(attrs Attrs) Option { return func(cmt *commenter) { cmt.providers = append(cmt.providers, AttrProviderFunc(func(ctx context.Context) Attrs { @@ -24,6 +29,7 @@ func WithAttrs(attrs Attrs) Option { } } +// WithAttrPairs configures commenter with attr pairs. func WithAttrPairs(pairs ...string) Option { return func(cmt *commenter) { cmt.providers = append(cmt.providers, AttrProviderFunc(func(ctx context.Context) Attrs { @@ -32,12 +38,14 @@ func WithAttrPairs(pairs ...string) Option { } } +// WithAttrProvider configures commenter with AttrProvider. func WithAttrProvider(prov AttrProvider) Option { return func(cmt *commenter) { cmt.providers = append(cmt.providers, prov) } } +// WithAttrFunc configures commenter with AttrProviderFunc. func WithAttrFunc(fn AttrProviderFunc) Option { return func(cmt *commenter) { cmt.providers = append(cmt.providers, fn)