Add missing doc comments to exported symbols (#392)

While going through pgroll codebase I see that it is also really nicely
documented overall.

I took this chance to add doc comments to the remaining non-documented
exported symbols.

Author: inelpandzic

pkg/migrations/check.go

@@ -2,6 +2,7 @@
 
 package migrations
 
+// Validate checks that the CheckConstraint is valid
 func (c *CheckConstraint) Validate() error {
 	if c.Name == "" {
 		return FieldRequiredError{Name: "name"}

pkg/migrations/column.go

@@ -2,20 +2,23 @@
 
 package migrations
 
+// IsNullable returns true if the column is nullable
 func (c *Column) IsNullable() bool {
 	if c.Nullable != nil {
 		return *c.Nullable
 	}
 	return false
 }
 
+// IsUnique returns true if the column values must be unique
 func (c *Column) IsUnique() bool {
 	if c.Unique != nil {
 		return *c.Unique
 	}
 	return false
 }
 
+// IsPrimaryKey returns true if the column is part of the primary key
 func (c *Column) IsPrimaryKey() bool {
 	if c.Pk != nil {
 		return *c.Pk

pkg/migrations/duplicate.go

@@ -14,6 +14,8 @@ import (
 	"github.com/xataio/pgroll/pkg/schema"
 )
 
+// Duplicator duplicates a column in a table, including all constraints and
+// comments.
 type Duplicator struct {
 	conn              db.DB
 	table             *schema.Table
@@ -40,16 +42,19 @@ func NewColumnDuplicator(conn db.DB, table *schema.Table, column *schema.Column)
 	}
 }
 
+// WithType sets the type of the new column.
 func (d *Duplicator) WithType(t string) *Duplicator {
 	d.withType = t
 	return d
 }
 
+// WithoutConstraint excludes a constraint from being duplicated.
 func (d *Duplicator) WithoutConstraint(c string) *Duplicator {
 	d.withoutConstraint = c
 	return d
 }
 
+// WithoutNotNull excludes the NOT NULL constraint from being duplicated.
 func (d *Duplicator) WithoutNotNull() *Duplicator {
 	d.withoutNotNull = true
 	return d
@@ -182,14 +187,17 @@ func (d *Duplicator) Duplicate(ctx context.Context) error {
 	return nil
 }
 
+// DiplicationName returns the name of a duplicated column.
 func DuplicationName(name string) string {
 	return "_pgroll_dup_" + name
 }
 
+// IsDuplicatedName returns true if the name is a duplicated column name.
 func IsDuplicatedName(name string) bool {
 	return strings.HasPrefix(name, "_pgroll_dup_")
 }
 
+// StripDuplicationPrefix removes the duplication prefix from a column name.
 func StripDuplicationPrefix(name string) string {
 	return strings.TrimPrefix(name, "_pgroll_dup_")
 }

pkg/migrations/fk_reference.go

@@ -8,6 +8,7 @@ import (
 	"github.com/xataio/pgroll/pkg/schema"
 )
 
+// Validate checks that the ForeignKeyReference is valid
 func (f *ForeignKeyReference) Validate(s *schema.Schema) error {
 	if f.Name == "" {
 		return FieldRequiredError{Name: "name"}

pkg/migrations/migrations.go

@@ -13,6 +13,7 @@ import (
 
 type CallbackFn func(int64)
 
+// Operation is an operation that can be applied to a schema
 type Operation interface {
 	// Start will apply the required changes to enable supporting the new schema
 	// version in the database (through a view)
@@ -22,31 +23,33 @@ type Operation interface {
 
 	// Complete will update the database schema to match the current version
 	// after calling Start.
-	// This method should be called once the previous version is no longer used
+	// This method should be called once the previous version is no longer used.
 	Complete(ctx context.Context, conn db.DB, tr SQLTransformer, s *schema.Schema) error
 
 	// Rollback will revert the changes made by Start. It is not possible to
 	// rollback a completed migration.
 	Rollback(ctx context.Context, conn db.DB, tr SQLTransformer) error
 
-	// Validate returns a descriptive error if the operation cannot be applied to the given schema
+	// Validate returns a descriptive error if the operation cannot be applied to the given schema.
 	Validate(ctx context.Context, s *schema.Schema) error
 }
 
 // IsolatedOperation is an operation that cannot be executed with other operations
-// in the same migration
+// in the same migration.
 type IsolatedOperation interface {
-	// this operation is isolated when executed on start, cannot be executed with other operations
+	// this operation is isolated when executed on start, cannot be executed with other operations.
 	IsIsolated() bool
 }
 
-// RequiresSchemaRefreshOperation is an operation that requires the resulting schema to be refreshed
+// RequiresSchemaRefreshOperation is an operation that requires the resulting schema to be refreshed.
 type RequiresSchemaRefreshOperation interface {
 	// this operation requires the resulting schema to be refreshed when executed on start
 	RequiresSchemaRefresh()
 }
 
+// SQLTransformer is an interface that can be used to transform SQL statements.
 type SQLTransformer interface {
+	// TransformSQL will transform the given SQL statement.
 	TransformSQL(sql string) (string, error)
 }
 

pkg/migrations/op_add_column.go

@@ -234,10 +234,12 @@ func (o *OpAddColumn) addCheckConstraint(ctx context.Context, conn db.DB) error
 	return err
 }
 
+// NotNullConstraintName returns the name of the NOT NULL constraint for the given column
 func NotNullConstraintName(columnName string) string {
 	return "_pgroll_check_not_null_" + columnName
 }
 
+// IsNotNullConstraintName returns true if the given name is a NOT NULL constraint name
 func IsNotNullConstraintName(name string) bool {
 	return strings.HasPrefix(name, "_pgroll_check_not_null_")
 }

pkg/migrations/op_common.go

@@ -36,10 +36,12 @@ const (
 
 const temporaryPrefix = "_pgroll_new_"
 
+// TemporaryName returns a temporary name for a given name.
 func TemporaryName(name string) string {
 	return temporaryPrefix + name
 }
 
+// ReadMigration reads a migration from an io.Reader, like a file.
 func ReadMigration(r io.Reader) (*Migration, error) {
 	byteValue, err := io.ReadAll(r)
 	if err != nil {
@@ -166,6 +168,7 @@ func (v Operations) MarshalJSON() ([]byte, error) {
 	return buf.Bytes(), nil
 }
 
+// OperationName returns the name of the operation.
 func OperationName(op Operation) OpName {
 	switch op.(type) {
 	case *OpCreateTable:

pkg/migrations/op_create_table.go

@@ -126,6 +126,7 @@ func columnsToSQL(cols []Column, tr SQLTransformer) (string, error) {
 	return sql, nil
 }
 
+// ColumnToSQL generates the SQL for a column definition.
 func ColumnToSQL(col Column, tr SQLTransformer) (string, error) {
 	sql := fmt.Sprintf("%s %s", pq.QuoteIdentifier(col.Name), col.Type)
 

pkg/migrations/op_drop_not_null.go

@@ -9,6 +9,7 @@ import (
 	"github.com/xataio/pgroll/pkg/schema"
 )
 
+// OpDropNotNull is an operation that drops the NOT NULL constraint from a column
 type OpDropNotNull struct {
 	Table  string `json:"table"`
 	Column string `json:"column"`

pkg/migrations/op_raw_sql.go

@@ -65,6 +65,7 @@ func (o *OpRawSQL) Validate(ctx context.Context, s *schema.Schema) error {
 	return nil
 }
 
+// IsIsolated returns true if the operation is isolated and should be run with other operations.
 func (o *OpRawSQL) IsIsolated() bool {
 	return !o.OnComplete
 }