docs: code and feature clarifications (#156)

Author: lorenarosati

expr/literals.go

@@ -34,6 +34,7 @@ type nestedLiteral interface {
 }
 
 type WithTypeLiteral interface {
+	// WithType attempts to convert a literal to a new type while preserving its value
 	WithType(types.Type) (Literal, error)
 }
 
@@ -97,7 +98,7 @@ type Literal interface {
 	ValueString() string
 }
 
-// A NullLiteral is a typed null, so it just contains its type
+// A NullLiteral is a typed null, so it just contains its type with no value
 type NullLiteral struct {
 	Type types.Type
 }
@@ -768,6 +769,7 @@ func getNullability(nullable bool) types.Nullability {
 	return types.NullabilityRequired
 }
 
+// A PrimitiveLiteral is a literal with one of the types specified in this interface
 type newPrimitiveLiteralTypes interface {
 	bool | int8 | int16 | ~int32 | ~int64 |
 		float32 | float64 | string

extensions/simple_extension.go

@@ -57,6 +57,7 @@ type TypeVariation struct {
 	Functions   TypeVariationFunctions
 }
 
+// FuncParameter is an argument of a function in its function definition
 type FuncParameter interface {
 	toTypeString() string
 	argumentMarker() // unexported marker method

extensions/variants.go

@@ -19,6 +19,7 @@ type FunctionVariant interface {
 	Args() FuncParameterList
 	Options() map[string]Option
 	URI() string
+	// ResolveType computes the return type of a function variant, given the input argument types
 	ResolveType(argTypes []types.Type, registry Set) (types.Type, error)
 	Variadic() *VariadicBehavior
 	// Match this function matches input arguments against this functions parameter list

literal/utils.go

@@ -14,6 +14,8 @@ import (
 	proto "github.com/substrait-io/substrait-protobuf/go/substraitpb"
 )
 
+//This package contains utility functions for creating literals
+
 func NewBool(value bool, nullable bool) expr.Literal {
 	return expr.NewPrimitiveLiteral(value, nullable)
 }

types/types.go

@@ -408,6 +408,7 @@ type (
 	// FuncArg corresponds to the protobuf FunctionArgument. Anything
 	// which could be a function argument should meet this interface.
 	// This is either an Expression, a Type, or an Enum (string).
+	// These are the actual arguments for a function present in a plan.
 	FuncArg interface {
 		fmt.Stringer
 		ToProtoFuncArg() *proto.FunctionArgument
@@ -419,7 +420,7 @@ type (
 	}
 
 	// Type corresponds to the proto.Type message and represents
-	// a specific type. These are types which can be present in plan (are serializable)
+	// a specific concrete type. These are types which can be present in plan (are serializable)
 	Type interface {
 		FuncArg
 		isRootRef()
@@ -469,8 +470,9 @@ type (
 		BaseString() string
 	}
 
-	// FuncDefArgType this represents a type used in function argument
-	// These type can't be present in plan (not serializable)
+	// FuncDefArgType represents a type used in a function argument
+	// This is an unresolved type of an argument present in the function definition.
+	// This type can't be present in plan (not serializable)
 	FuncDefArgType interface {
 		fmt.Stringer
 		//SetNullability set nullability as given argument
@@ -913,6 +915,11 @@ func (s *PrimitiveType[T]) WithParameters([]interface{}) (Type, error) {
 }
 
 // create type aliases to the generic structs
+//
+// The parameterized types below use parameterizedTypeSingleIntegerParam to
+// create types that accept a single integer parameter (e.g., precision)
+// Other parameterized types (e.g. DecimalType) have their
+// own dedicated type definitions (ParameterizedDecimalType) rather than using the generic parameterized type.
 type (
 	BooleanType                           = PrimitiveType[bool]
 	Int8Type                              = PrimitiveType[int8]