restore a bunch of comments

Author: James Cor

sql/column.go

@@ -26,19 +26,35 @@ import (
 //	A column is a named component of a table. It has a data type, a default,
 //	and a nullability characteristic.
 type Column struct {
-	Type           Type
-	Generated      *ColumnDefaultValue
-	Default        *ColumnDefaultValue
-	OnUpdate       *ColumnDefaultValue
-	Name           string
-	Source         string
+	// Type is the data type of the column.
+	Type Type
+	// Default contains the default value of the column or nil if it was not explicitly defined.
+	Default *ColumnDefaultValue
+	// Generated is non-nil if the column is defined with a generated value. Mutually exclusive with Default
+	Generated *ColumnDefaultValue
+	// OnUpdate contains the on update value of the column or nil if it was not explicitly defined.
+	OnUpdate *ColumnDefaultValue
+	// Name is the name of the column.
+	Name string
+	// Source is the name of the table this column came from.
+	Source string
+	// DatabaseSource is the name of the database this column came from.
 	DatabaseSource string
-	Comment        string
-	Extra          string
-	PrimaryKey     bool
-	Nullable       bool
-	Virtual        bool
-	AutoIncrement  bool
+	// Comment contains the string comment for this column.
+	Comment string
+	// Extra contains any additional information to put in the `extra` column under `information_schema.columns`.
+	Extra string
+	// PrimaryKey is true if the column is part of the primary key for its table.
+	PrimaryKey bool
+	// Nullable is true if the column can contain NULL values, or false
+	// otherwise.
+	Nullable bool
+	// Virtual is true if the column is defined as a virtual column. Generated must be non-nil in this case.
+	// Virtual column values will be provided for write operations, in case integrators need to use them to update
+	// indexes, but must not be returned in rows from tables that include them.
+	Virtual bool
+	// AutoIncrement is true if the column auto-increments.
+	AutoIncrement bool
 }
 
 // Check ensures the value is correct for this column.

sql/constraints.go

@@ -45,18 +45,30 @@ func (f ForeignKeyReferentialAction) IsEquivalentToRestrict() bool {
 
 // ForeignKeyConstraint declares a constraint between the columns of two tables.
 type ForeignKeyConstraint struct {
-	Name           string
-	Database       string
-	SchemaName     string
-	Table          string
+	// Name is the name of the foreign key constraint
+	Name string
+	// Database is the name of the database of the table with the constraint
+	Database string
+	// SchemaName is the name of the schema of the table, for databases that support schemas.
+	SchemaName string
+	// Table is the name of the table with the constraint
+	Table string
+	// ParentDatabase is the name of the database of the parent table
 	ParentDatabase string
-	ParentSchema   string
-	ParentTable    string
-	OnUpdate       ForeignKeyReferentialAction
-	OnDelete       ForeignKeyReferentialAction
-	Columns        []string
-	ParentColumns  []string
-	IsResolved     bool
+	// ParentSchema is the name of the schema of the parent table, for databases that support schemas.
+	ParentSchema string
+	// ParentTable is the name of the parent table
+	ParentTable string
+	// OnUpdate is the action to take when the constraint is violated when a row in the parent table is updated
+	OnUpdate ForeignKeyReferentialAction
+	// OnDelete is the action to take when the constraint is violated when a row in the parent table is deleted
+	OnDelete ForeignKeyReferentialAction
+	// Columns is the list of columns in the table that are part of the foreign key
+	Columns []string
+	// ParentColumns is the list of columns in the parent table that are part of the foreign key
+	ParentColumns []string
+	// IsResolved is true if the foreign key has been resolved, false otherwise
+	IsResolved bool
 }
 
 // IsSelfReferential returns whether this foreign key represents a self-referential foreign key.

sql/core.go

@@ -479,13 +479,36 @@ var _ SystemVariable = (*MysqlSystemVariable)(nil)
 
 // MysqlSystemVariable represents a mysql system variable.
 type MysqlSystemVariable struct {
-	Type              Type
-	Default           interface{}
-	Scope             *MysqlScope
-	NotifyChanged     func(*Context, SystemVariableScope, SystemVarValue) error
-	ValueFunction     func() (interface{}, error)
-	Name              string
-	Dynamic           bool
+	// Type defines the type of the system variable. This may be a special type not accessible to standard MySQL operations.
+	Type Type
+	// Default defines the default value of the system variable.
+	Default interface{}
+	// Scope defines the scope of the system variable, which is either Global, Session, or Both.
+	Scope *MysqlScope
+	// NotifyChanged is called by the engine if the value of this variable
+	// changes during runtime.  It is typically |nil|, but can be used for
+	// system variables which control the behavior of the running server.
+	// For example, replication threads might need to be started or stopped
+	// when replication is enabled or disabled. This provides a scalable
+	// alternative to polling.
+	//
+	// Calls to NotifyChanged are serialized for a given system variable in
+	// the global context and in a particular session. They should never
+	// block.  NotifyChanged is not called when a new system variable is
+	// registered.
+	NotifyChanged func(*Context, SystemVariableScope, SystemVarValue) error
+	// ValueFunction defines an optional function that is executed to provide
+	// the value of this system variable whenever it is requested. System variables
+	// that provide a ValueFunction should also set Dynamic to false, since they
+	// cannot be assigned a value and will return a read-only error if tried.
+	ValueFunction func() (interface{}, error)
+	// Name is the name of the system variable.
+	Name string
+	// Dynamic defines whether the variable may be written to during runtime. Variables with this set to `false` will
+	// return an error if a user attempts to set a value.
+	Dynamic bool
+	// SetVarHintApplies defines if the variable may be set for a single query using SET_VAR().
+	// https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html#optimizer-hints-set-var
 	SetVarHintApplies bool
 }
 

sql/expression/function/aggregation/unary_agg_buffers.go

@@ -52,7 +52,7 @@ func (a *anyValueBuffer) Dispose() {
 }
 
 type sumBuffer struct {
-	sum   interface{}
+	sum   interface{} // sum is either decimal.Decimal or float64
 	expr  sql.Expression
 	isnil bool
 }

sql/expression/function/aggregation/window_functions.go

@@ -93,9 +93,10 @@ func (a *AnyValueAgg) Compute(ctx *sql.Context, interval sql.WindowInterval, buf
 }
 
 type SumAgg struct {
-	expr           sql.Expression
-	framer         sql.WindowFramer
-	prefixSum      []float64 // use prefix sums to quickly calculate arbitrary frame sum within partition
+	expr   sql.Expression
+	framer sql.WindowFramer
+	// use prefix sums to quickly calculate arbitrary frame sum within partition
+	prefixSum      []float64
 	partitionStart int
 	partitionEnd   int
 }

sql/fast_int_set.go

@@ -48,6 +48,9 @@ import (
 // allocations when the values are small. It is not thread-safe.
 type FastIntSet struct {
 	large *intsets.Sparse
+	// We use a uint64 as long as all elements are between 0 and 63. If we add an
+	// element outside of this range, we switch to Sparse. We don't just use the
+	// latter directly because it's larger and can't be passed around by value.
 	small uint64
 }
 

sql/index_registry.go

@@ -32,11 +32,12 @@ type IndexRegistry struct {
 	refCounts        map[indexKey]int
 	deleteIndexQueue map[indexKey]chan<- struct{}
 	indexLoaders     map[dbTableTuple][]func(ctx *Context) error
-	Root             string
-	indexOrder       []indexKey
-	mut              sync.RWMutex
-	driversMut       sync.RWMutex
-	rcmut            sync.RWMutex
+	// Root path where all the data of the indexes is stored on disk.
+	Root       string
+	indexOrder []indexKey
+	mut        sync.RWMutex
+	driversMut sync.RWMutex
+	rcmut      sync.RWMutex
 }
 
 // NewIndexRegistry returns a new Index Registry.

sql/memo/join_order_builder.go

@@ -122,6 +122,12 @@ import (
 //
 // TODO: null rejecting tables
 type joinOrderBuilder struct {
+	// plans maps from a set of base relations to the memo group for the join tree
+	// that contains those relations (and only those relations). As an example,
+	// the group for [xy, ab, uv] might contain the join trees (xy, (ab, uv)),
+	// ((xy, ab), uv), (ab, (xy, uv)), etc.
+	//
+	// The group for a single base relation is the base relation itself.
 	m                         *Memo
 	innerEdges                edgeSet
 	nonInnerEdges             edgeSet
@@ -362,7 +368,7 @@ func (j *joinOrderBuilder) ensureClosure(grp *ExprGroup) {
 
 // hasEqEdge returns true if the inner edges include a direct equality between
 // the two given columns (e.g. x = a).
-func (j joinOrderBuilder) hasEqEdge(leftCol, rightCol sql.ColumnId) bool {
+func (j *joinOrderBuilder) hasEqEdge(leftCol, rightCol sql.ColumnId) bool {
 	for idx, ok := j.innerEdges.Next(0); ok; idx, ok = j.innerEdges.Next(idx + 1) {
 		for _, f := range j.edges[idx].filters {
 			var l *expression.GetField
@@ -839,24 +845,49 @@ func (j *joinOrderBuilder) allEdges() edgeSet {
 // tree. It is used in calculating the total eligibility sets for edges from any
 // 'parent' joins which were originally above this one in the tree.
 type operator struct {
-	leftEdges     edgeSet
-	rightEdges    edgeSet
-	leftVertices  vertexSet
+	// leftEdges is the set of edges that were constructed from join operators
+	// that were in the left input of the original join operator.
+	leftEdges edgeSet
+	// rightEdgers is the set of edges that were constructed from join operators
+	// that were in the right input of the original join operator.
+	rightEdges edgeSet
+	// leftVertices is the set of vertexes (base relations) that were in the left
+	// input of the original join operator.
+	leftVertices vertexSet
+	// rightVertices is the set of vertexes (base relations) that were in the
+	// right input of the original join operator.
 	rightVertices vertexSet
-	joinType      plan.JoinType
+	// joinType is the operator type of the original join operator.
+	joinType plan.JoinType
 }
 
 // edge is a generalization of a join edge that embeds rules for
 // determining the applicability of arbitrary subtrees. An edge is added to the
 // join graph when a new plan can be constructed between two vertexSet.
 type edge struct {
-	freeVars         sql.ColSet
-	op               *operator
-	filters          []sql.Expression
-	rules            []conflictRule
+	freeVars sql.ColSet
+	// op is the original join node source for the edge. there are multiple edges
+	// per op for inner joins with conjunct-predicate join conditions. Different predicates
+	// will have different conflict rules.
+	op *operator
+	// filters is the set of join filters that will be used to construct new join
+	// ON conditions.
+	filters []sql.Expression
+	// rules is a set of conflict rules which must evaluate to true in order for
+	// a join between two sets of vertexes to be valid.
+	rules []conflictRule
+	// nullRejectedRels is the set of vertexes on which nulls are rejected by the
+	// filters. We do not set any nullRejectedRels currently, which is not accurate
+	// but prevents potentially invalid transformations.
 	nullRejectedRels vertexSet
-	ses              vertexSet
-	tes              vertexSet
+	// ses is the syntactic eligibility set of the edge; in other words, it is the
+	// set of base relations (tables) referenced by the filters field.
+	ses vertexSet
+	// tes is the total eligibility set of the edge. The TES gives the set of base
+	// relations (vertexes) that must be in the input of any join that uses the
+	// filters from this edge in its ON condition. The TES is initialized with the
+	// SES, and then expanded by the conflict detection algorithm.
+	tes vertexSet
 }
 
 func (e *edge) populateEdgeProps(tableIds []sql.TableId, edges []edge) {

sql/plan/alter_index.go

@@ -42,21 +42,35 @@ const (
 )
 
 type AlterIndex struct {
-	Db    sql.Database
+	// ddlNode references to the database that is being operated on
+	Db sql.Database
+	// Table is the table that is being referenced
 	Table sql.TableNode
 
-	IndexName         string
+	// IndexName is the index name, and in the case of a RENAME it represents the new name
+	IndexName string
+	// PreviousIndexName states the old name when renaming an index
 	PreviousIndexName string
-	Comment           string
+	// Comment is the comment that was left at index creation, if any
+	Comment string
 
+	// TargetSchema Analyzer state.
 	targetSchema sql.Schema
-	Columns      []sql.IndexColumn
-	Using        sql.IndexUsing
-	Constraint   sql.IndexConstraint
-
-	Action      IndexAction
-	IfExists    bool
+	// Columns contains the column names (and possibly lengths) when creating an index
+	Columns []sql.IndexColumn
+	// TODO: This should just use sql.IndexDef
+	// Using states whether you're using BTREE, HASH, or non
+	Using sql.IndexUsing
+	// Constraint specifies whether this is UNIQUE, FULLTEXT, SPATIAL, or none
+	Constraint sql.IndexConstraint
+
+	// Action states whether it's a CREATE, DROP, or RENAME
+	Action IndexAction
+	// IfExists indicates if we should error when deleting an index that doesn't exist
+	IfExists bool
+	// IfNotExists indicates if we should error when creating a duplicate index
 	IfNotExists bool
+	// DisableKeys determines whether to DISABLE KEYS if true or ENABLE KEYS if false
 	DisableKeys bool
 }
 

sql/plan/delete.go

@@ -28,10 +28,15 @@ var ErrDeleteFromNotSupported = errors.NewKind("table doesn't support DELETE FRO
 // DeleteFrom is a node describing a deletion from some table.
 type DeleteFrom struct {
 	UnaryNode
+	// targets are the explicitly specified table nodes from which rows should be deleted. For simple DELETES against a
+	// single source table, targets do NOT need to be explicitly specified and will not be set here. For DELETE FROM JOIN
+	// statements, targets MUST be explicitly specified by the user and will be populated here.
 	explicitTargets []sql.Node
-	Returning       []sql.Expression
-	RefsSingleRel   bool
-	IsProcNested    bool
+	// Returning is a list of expressions to return after the delete operation. This feature is not
+	// supported in MySQL's syntax, but is exposed through PostgreSQL's syntax.
+	Returning     []sql.Expression
+	RefsSingleRel bool
+	IsProcNested  bool
 }
 
 var _ sql.Databaseable = (*DeleteFrom)(nil)