additional comments

column.go

@@ -15,24 +15,56 @@ const (
 // Event ...
 type Event string
 
-// Column ...
+// Column describes database column.
 type Column struct {
-	Name, ShortName, Collate, Check                                      string
-	Default                                                              map[Event]string
-	NotNull, Unique, PrimaryKey, Index                                   bool
-	Type                                                                 Type
-	Table                                                                *Table
-	Reference                                                            *Column
-	ReferenceOptions                                                     []RelationshipOption
-	Match, OnDelete, OnUpdate                                            int32
-	NoInherit, DeferrableInitiallyDeferred, DeferrableInitiallyImmediate bool
-	// Dynamic
+	// Name is a column name.
+	Name string
+	// ShortName is a column short name. It is used in queries when column name is ambiguous.
+	ShortName string
+	// Collate is a collation for column.
+	// It allows to specify the collation order for character data.
+	Collate string
+	// Check is a check constraint.
+	// It allows to specify a predicate that must be satisfied by each row of the table.
+	Check string
+	// Default is a default value for column for given event.
+	// For example for insert event it will be used when no value is provided.
+	Default map[Event]string
+	// NotNull if true means that column cannot be null.
+	NotNull bool
+	// Unique if true means that column value must be unique.
+	Unique bool
+	// PrimaryKey if true means that column is a primary key.
+	PrimaryKey bool
+	// Index if true means that column is indexed.
+	Index bool
+	// Type is a column type.
+	Type Type
+	// Table is a table that column belongs to.
+	Table *Table
+	// Reference is a column that this column references.
+	Reference *Column
+	// ReferenceOptions are options for reference.
+	ReferenceOptions []RelationshipOption
+	// Match is a match option for foreign key constraint.
+	Match int32
+	// OnDelete is a ON DELETE clause that specifies the action to perform when a referenced row in the referenced table is being deleted.
+	OnDelete int32
+	// OnUpdate is a ON UPDATE clause that specifies the action to perform when a referenced column in the referenced table is being updated to a new value.
+	OnUpdate int32
+	// NoInherit if true means that column is not inherited by child tables.
+	NoInherit                    bool
+	DeferrableInitiallyDeferred  bool
+	DeferrableInitiallyImmediate bool
+	// IsDynamic if true means that column is not stored in database, but is dynamically created using function.
 	IsDynamic bool
-	Func      *Function
-	Columns   Columns
+	// Func is a function that is used to create dynamic column.
+	Func *Function
+	// Columns are columns that are used by dynamic column function.
+	Columns Columns
 }
 
-// NewColumn ...
+// NewColumn initializes new instance of Column.
 func NewColumn(n string, t Type, opts ...ColumnOption) *Column {
 	c := &Column{
 		Name: n,
@@ -46,7 +78,7 @@ func NewColumn(n string, t Type, opts ...ColumnOption) *Column {
 	return c
 }
 
-// NewDynamicColumn ...
+// NewDynamicColumn initializes new instance of Column that is created using function.
 func NewDynamicColumn(n string, f *Function, cs ...*Column) *Column {
 	return &Column{
 		IsDynamic: true,

function.go

@@ -21,9 +21,10 @@ const (
 	FunctionBehaviourStable
 )
 
+// FunctionBehaviour is a function behaviour, it can be volatile, immutable or stable.
 type FunctionBehaviour int
 
-// Function ...
+// Function describes database function.
 type Function struct {
 	Name      string
 	BuiltIn   bool
@@ -33,13 +34,14 @@ type Function struct {
 	Args      []*FunctionArg
 }
 
-// FunctionArg ...
+// FunctionArg is a function argument, it is used to describe function signature.
 type FunctionArg struct {
 	Name string
 	Type Type
 }
 
-// FunctionNow ...
+// FunctionNow is a helper function that creates now() function.
+// Now() returns current timestamp with time zone (abbreviated as timestamptz).
 func FunctionNow() *Function {
 	return &Function{
 		Name:    "now",

relationship.go

@@ -34,14 +34,31 @@ const (
 	SetDefault
 )
 
-// RelationshipType ...
+// RelationshipType can be used to describe relationship between tables.
+// It can be one to one, one to many, many to one or many to many.
 type RelationshipType int
 
-// Relationship ...
+// Relationship describes database relationship.
+// Usually it is used to describe foreign key constraint.
 type Relationship struct {
-	Bidirectional                           bool
-	Type                                    RelationshipType
-	OwnerName, InversedName                 string
+	// Bidirectional if true means that relationship is bidirectional.
+	// It is useful when we want to get all related rows from both tables.
+	// If true, the library will generate additional methods for both tables.
+	Bidirectional bool
+	// Type defines relationship type.
+	Type RelationshipType
+	// OwnerName is a name of relationship from owner table perspective.
+	// For example if we have table A and table B and relationship from A to B,
+	// then owner name is a name of relationship from A perspective.
+	// It is a good practice to give descriptive names to relationships.
+	OwnerName string
+	// InversedName is a name of relationship from inversed table perspective.
+	// For example if we have table A and table B and relationship from A to B,
+	// then inversed name is a name of relationship from B perspective.
+	// If not set, the library will generate it automatically.
+	// It is useful when we want to have two relationships between two tables or when table self references itself.
+	// It is a good practice to give descriptive names to relationships.
+	InversedName                            string
 	OwnerTable, InversedTable, ThroughTable *Table
 	OwnerForeignKey, InversedForeignKey     *Constraint
 	OwnerColumns, InversedColumns           Columns
@@ -64,22 +81,26 @@ func newRelationship(owner, inversed, through *Table, rt RelationshipType, opts
 	return r
 }
 
-// OneToOne ...
+// OneToOne is a handy constructor that instantiates basic one-to-one relationship.
+// It can be adjusted using RelationshipOption.
 func OneToOne(t *Table, opts ...RelationshipOption) *Relationship {
 	return newRelationship(nil, t, nil, RelationshipTypeOneToOne, opts...)
 }
 
-// OneToMany ...
+// OneToMany is a handy constructor that instantiates basic one-to-many relationship.
+// It can be adjusted using RelationshipOption.
 func OneToMany(t *Table, opts ...RelationshipOption) *Relationship {
 	return newRelationship(t, nil, nil, RelationshipTypeOneToMany, opts...)
 }
 
-// ManyToOne ...
+// ManyToOne is a handy constructor that instantiates basic many-to-one relationship.
+// It can be adjusted using RelationshipOption.
 func ManyToOne(t *Table, opts ...RelationshipOption) *Relationship {
 	return newRelationship(nil, t, nil, RelationshipTypeManyToOne, opts...)
 }
 
-// ManyToMany ...
+// ManyToMany is a handy constructor that instantiates basic many-to-many relationship.
+// It can be adjusted using RelationshipOption.
 func ManyToMany(t1 *Table, t2 *Table, opts ...RelationshipOption) *Relationship {
 	return newRelationship(t1, t2, nil, RelationshipTypeManyToMany, opts...)
 }
@@ -105,7 +126,7 @@ func WithOwnerForeignKey(primaryColumns, referenceColumns Columns, opts ...Const
 	}
 }
 
-// WithInversedForeignKey ...
+// WithInversedForeignKey adjust relationship to have inversed foreign key.
 func WithInversedForeignKey(primaryColumns, referenceColumns Columns, opts ...ConstraintOption) RelationshipOption {
 	return func(r *Relationship) {
 		if r.Type != RelationshipTypeManyToMany {
@@ -122,7 +143,7 @@ func WithInversedForeignKey(primaryColumns, referenceColumns Columns, opts ...Co
 	}
 }
 
-// WithForeignKey ...
+// WithForeignKey adjust relationship to have foreign key.
 func WithForeignKey(primaryColumns, referenceColumns Columns, opts ...ConstraintOption) RelationshipOption {
 	return func(r *Relationship) {
 		if r.Type == RelationshipTypeManyToMany {
@@ -139,28 +160,28 @@ func WithForeignKey(primaryColumns, referenceColumns Columns, opts ...Constraint
 	}
 }
 
-// WithInversedName ...
+// WithInversedName adjust relationship by setting inversed name.
 func WithInversedName(s string) RelationshipOption {
 	return func(r *Relationship) {
 		r.InversedName = s
 	}
 }
 
-// WithColumnName ...
+// WithColumnName adjust relationship by setting column name.
 func WithColumnName(n string) RelationshipOption {
 	return func(r *Relationship) {
 		r.ColumnName = n
 	}
 }
 
-// WithBidirectional ...
+// WithBidirectional adjust relationship by setting bidirectional flag.
 func WithBidirectional() RelationshipOption {
 	return func(r *Relationship) {
 		r.Bidirectional = true
 	}
 }
 
-// WithOwnerName ...
+// WithOwnerName adjust relationship by setting owner name.
 func WithOwnerName(s string) RelationshipOption {
 	return func(r *Relationship) {
 		r.OwnerName = s

schema.go

@@ -1,15 +1,22 @@
 package pqt
 
-// Schema ...
+// Schema describes database schema.
+// It is a collection of tables, functions and types.
 type Schema struct {
-	Name        string
+	// Name is a schema name.
+	Name string
+	// IfNotExists if true means that schema should be created only if it does not exist.
+	// If true, creation process will not fail if schema already exists.
 	IfNotExists bool
-	Tables      []*Table
-	Functions   []*Function
-	Types       []Type
+	// Tables is a collection of tables that schema contains.
+	Tables []*Table
+	// Functions is a collection of functions that schema contains.
+	Functions []*Function
+	// Types is a collection of types that schema contains.
+	Types []Type
 }
 
-// NewSchema ...
+// NewSchema initializes new instance of Schema for given name and options.
 func NewSchema(name string, opts ...SchemaOption) *Schema {
 	s := &Schema{
 		Name: name,
@@ -22,7 +29,7 @@ func NewSchema(name string, opts ...SchemaOption) *Schema {
 	return s
 }
 
-// AddTable ...
+// AddTable adds table to schema.
 func (s *Schema) AddTable(t *Table) *Schema {
 	if s.Tables == nil {
 		s.Tables = make([]*Table, 0, 1)
@@ -33,6 +40,7 @@ func (s *Schema) AddTable(t *Table) *Schema {
 	return s
 }
 
+// AddFunction adds function to schema.
 func (s *Schema) AddFunction(f *Function) *Schema {
 	if s.Functions == nil {
 		s.Functions = make([]*Function, 0, 1)

table.go

@@ -10,12 +10,18 @@ type Table struct {
 	self                                 bool
 	Name, ShortName, Collate, TableSpace string
 	IfNotExists, Temporary               bool
-	Schema                               *Schema
-	Columns                              Columns
-	Constraints                          Constraints
-	OwnedRelationships                   []*Relationship
-	InversedRelationships                []*Relationship
-	ManyToManyRelationships              []*Relationship
+	// Schema references parent schema.
+	Schema *Schema
+	// Columns is a collection of columns that table contains.
+	Columns Columns
+	// Constraints is a collection of constraints that table contains.
+	Constraints Constraints
+	// OwnedRelationships is a collection of relationships that table owns.
+	OwnedRelationships []*Relationship
+	// InversedRelationships is a collection of relationships that table is inversed in.
+	InversedRelationships []*Relationship
+	// ManyToManyRelationships is a collection of relationships that table is inversed in.
+	ManyToManyRelationships []*Relationship
 }
 
 // NewTable allocates new table using given name and options.
@@ -297,7 +303,7 @@ func WithTableSpace(s string) TableOption {
 	}
 }
 
-// WithTableShortName ...
+// WithTableShortName pass the short name of the table.
 func WithTableShortName(s string) TableOption {
 	return func(t *Table) {
 		t.ShortName = s