docs(pkg/common): add comprehensive GoDoc comments for public contracts

pkg/common/diffstyle.go

@@ -9,7 +9,10 @@ package common
 type DiffStyle uint8
 
 const (
+	// DiffUnified displays changes in the standard unified diff format.
 	DiffUnified DiffStyle = iota
+	// DiffSide displays changes in side-by-side columns.
 	DiffSide
+	// DiffNone suppresses diff rendering.
 	DiffNone
 )

pkg/common/format.go

@@ -9,6 +9,8 @@ package common
 type Format uint8
 
 const (
+	// FormatText produces human-readable, formatted terminal or plain text output.
 	FormatText Format = iota
+	// FormatJSON produces machine-readable JSON output representing findings or layouts.
 	FormatJSON
 )

pkg/common/types.go

@@ -13,49 +13,82 @@ import (
 // Target is a loader-agnostic view of one typed Go package: everything the
 // analyzer and the layout inspector need, without exposing go/packages.Package.
 type Target struct {
-	PkgPath   string
-	Fset      *token.FileSet
-	Syntax    []*ast.File
-	Types     *types.Package
+	// PkgPath is the full Go package import path (e.g., "github.com/peczenyj/structalign/pkg/common").
+	PkgPath string
+	// Fset is the FileSet used to resolve AST positions within this package.
+	Fset *token.FileSet
+	// Syntax is the parsed AST slice representing all Go source files in the package.
+	Syntax []*ast.File
+	// Types is the type system package representation containing scopes and type definitions.
+	Types *types.Package
+	// TypesInfo contains the type-checker's AST-to-type associations, definitions, and uses.
 	TypesInfo *types.Info
-	Sizes     Sizes
-	Errors    []error
+	// Sizes provides the target-architecture specific type sizing logic.
+	Sizes Sizes
+	// Errors lists any syntax or type-checking errors encountered during package loading.
+	Errors []error
 }
 
 // Finding is one struct whose fields could be reordered to use less memory.
 type Finding struct {
-	Package    string
-	Fset       *token.FileSet
-	Pos        token.Pos
-	Name       string // enclosing named type, or "" for an anonymous struct
-	TypeParams string // type-parameter names for a generic type, e.g. "[T]" (else "")
-	Message    string // analyzer diagnostic (carries the size info)
-	Original   string // current struct source ("struct{...}")
-	Proposed   string // reordered struct from the analyzer's SuggestedFix
-	OldSize    int64  // current struct size from the analyzer message (0 if unknown)
-	NewSize    int64  // proposed (optimal) size from the analyzer message (0 if unknown)
+	// Package is the name of the package containing the finding.
+	Package string
+	// Fset is the FileSet used to decode the Pos location into file, line, and column.
+	Fset *token.FileSet
+	// Pos is the position of the struct declaration.
+	Pos token.Pos
+	// Name is the enclosing named type name, or an empty string for an anonymous struct.
+	Name string
+	// TypeParams represents the type-parameter names for a generic type, e.g. "[T]" (else empty).
+	TypeParams string
+	// Message is the high-level human-readable size comparison diagnostic.
+	Message string
+	// Original is the original struct source code representation (e.g. "struct{...}").
+	Original string
+	// Proposed is the reordered struct source code from the analyzer's suggested fix.
+	Proposed string
+	// OldSize is the original struct size in bytes.
+	OldSize int64
+	// NewSize is the proposed (reordered) struct size in bytes.
+	NewSize int64
 }
 
 // LayoutField is one field's place in a struct's memory layout.
 type LayoutField struct {
-	Name    string
-	Type    string
-	Tag     string // raw struct tag without backticks, or ""
-	Assume  string // for a generic field, the assumed type param(s), e.g. "T=any" (else "")
-	Offset  int64
-	Size    int64
-	Align   int64
-	Padding int64 // padding inserted after this field
+	// Name is the name of the struct field.
+	Name string
+	// Type is the type of the field represented as a string.
+	Type string
+	// Tag is the raw struct field tag (excluding surrounding backticks), or empty if none exists.
+	Tag string
+	// Assume is the assumed type parameter(s) for a generic field, e.g. "T=any", or empty if none exists.
+	Assume string
+	// Offset is the byte offset of the field within the struct layout.
+	Offset int64
+	// Size is the size of the field's type in bytes.
+	Size int64
+	// Align is the alignment of the field's type in bytes.
+	Align int64
+	// Padding is the trailing padding in bytes inserted after this field.
+	Padding int64
 }
 
 // Layout is one named struct's computed memory layout.
 type Layout struct {
-	Package    string
-	Name       string
-	TypeParams string // for a generic type, e.g. "[T]" (else "")
-	Note       string // optional caveat shown above the struct (e.g. the generic disclaimer)
-	Total      int64
-	Align      int64
-	Padding    int64 // total padding across all fields
-	Fields     []LayoutField
+	// Package is the name of the package declaring the struct.
+	Package string
+	// Name is the name of the struct type.
+	Name string
+	// TypeParams represents the type parameters for a generic type, e.g. "[T]" (else empty).
+	TypeParams string
+	// Note is an optional message warning or disclaimer regarding the layout details.
+	Note string
+	// Total is the total size of the struct in bytes, including padding.
+	Total int64
+	// Align is the alignment requirement of the struct in bytes.
+	Align int64
+	// Padding is the sum of all padding bytes within the struct.
+	Padding int64
+	// Fields lists the struct's fields in memory-layout order.
+	Fields []LayoutField
 }