From d52b9cdc14675d82d2c0f802b36548c6a1edcd10 Mon Sep 17 00:00:00 2001 From: Hein Date: Sun, 28 Dec 2025 11:42:05 +0200 Subject: [PATCH] Enhanced godoc --- pkg/models/dctx.go | 23 ++++++++----- pkg/models/flatview.go | 25 +++++++------- pkg/models/models.go | 68 +++++++++++++++++++++++++++------------ pkg/models/summaryview.go | 20 ++++++------ 4 files changed, 88 insertions(+), 48 deletions(-) diff --git a/pkg/models/dctx.go b/pkg/models/dctx.go index 76ea790..4034c2d 100644 --- a/pkg/models/dctx.go +++ b/pkg/models/dctx.go @@ -2,7 +2,13 @@ package models import "encoding/xml" -// DCTXDictionary represents the root element of a DCTX file +// DCTX File Format Models +// +// This file defines the data structures for parsing and generating DCTX +// (Data Dictionary) XML files, which are used by Clarion development tools +// for database schema definitions. + +// DCTXDictionary represents the root element of a DCTX file. type DCTXDictionary struct { XMLName xml.Name `xml:"Dictionary"` Name string `xml:"Name,attr"` @@ -11,7 +17,7 @@ type DCTXDictionary struct { Relations []DCTXRelation `xml:"Relation,omitempty"` } -// DCTXTable represents a table definition in DCTX +// DCTXTable represents a table definition in DCTX format. type DCTXTable struct { Guid string `xml:"Guid,attr"` Name string `xml:"Name,attr"` @@ -25,7 +31,8 @@ type DCTXTable struct { Options []DCTXOption `xml:"Option,omitempty"` } -// DCTXField represents a field/column definition in DCTX +// DCTXField represents a field/column definition in DCTX format. +// Fields can be nested for GROUP structures. type DCTXField struct { Guid string `xml:"Guid,attr"` Name string `xml:"Name,attr"` @@ -37,7 +44,7 @@ type DCTXField struct { Options []DCTXOption `xml:"Option,omitempty"` } -// DCTXKey represents an index or key definition in DCTX +// DCTXKey represents an index or key definition in DCTX format. type DCTXKey struct { Guid string `xml:"Guid,attr"` Name string `xml:"Name,attr"` @@ -49,7 +56,7 @@ type DCTXKey struct { Components []DCTXComponent `xml:"Component"` } -// DCTXComponent represents a component of a key (field reference) +// DCTXComponent represents a component of a key, referencing a field in the index. type DCTXComponent struct { Guid string `xml:"Guid,attr"` FieldId string `xml:"FieldId,attr,omitempty"` @@ -57,14 +64,14 @@ type DCTXComponent struct { Ascend bool `xml:"Ascend,attr,omitempty"` } -// DCTXOption represents a property option in DCTX +// DCTXOption represents a property option in DCTX format for metadata storage. type DCTXOption struct { Property string `xml:"Property,attr"` PropertyType string `xml:"PropertyType,attr,omitempty"` PropertyValue string `xml:"PropertyValue,attr"` } -// DCTXRelation represents a relationship/foreign key in DCTX +// DCTXRelation represents a relationship/foreign key in DCTX format. type DCTXRelation struct { Guid string `xml:"Guid,attr"` PrimaryTable string `xml:"PrimaryTable,attr"` @@ -77,7 +84,7 @@ type DCTXRelation struct { PrimaryMappings []DCTXFieldMapping `xml:"PrimaryMapping,omitempty"` } -// DCTXFieldMapping represents a field mapping in a relation +// DCTXFieldMapping represents a field mapping in a relation for multi-column foreign keys. type DCTXFieldMapping struct { Guid string `xml:"Guid,attr"` Field string `xml:"Field,attr"` diff --git a/pkg/models/flatview.go b/pkg/models/flatview.go index c6cc3de..687ee3c 100644 --- a/pkg/models/flatview.go +++ b/pkg/models/flatview.go @@ -2,11 +2,14 @@ package models import "fmt" -// ============================================================================= -// Flat/Denormalized Views - Flattened structures with fully qualified names -// ============================================================================= +// Flat/Denormalized Views +// +// This file provides flattened data structures with fully qualified names +// for easier querying and analysis of database schemas without navigating +// nested hierarchies. -// FlatColumn represents a column with full context in a single structure +// FlatColumn represents a column with full database context in a single structure. +// It includes fully qualified names for easy identification and querying. type FlatColumn struct { DatabaseName string `json:"database_name" yaml:"database_name" xml:"database_name"` SchemaName string `json:"schema_name" yaml:"schema_name" xml:"schema_name"` @@ -25,7 +28,7 @@ type FlatColumn struct { Comment string `json:"comment,omitempty" yaml:"comment,omitempty" xml:"comment,omitempty"` } -// ToFlatColumns converts a Database to a slice of FlatColumns +// ToFlatColumns converts a Database to a slice of FlatColumns for denormalized access to all columns. func (d *Database) ToFlatColumns() []*FlatColumn { flatColumns := make([]*FlatColumn, 0) @@ -56,7 +59,7 @@ func (d *Database) ToFlatColumns() []*FlatColumn { return flatColumns } -// FlatTable represents a table with full context +// FlatTable represents a table with full database context and aggregated counts. type FlatTable struct { DatabaseName string `json:"database_name" yaml:"database_name" xml:"database_name"` SchemaName string `json:"schema_name" yaml:"schema_name" xml:"schema_name"` @@ -70,7 +73,7 @@ type FlatTable struct { IndexCount int `json:"index_count" yaml:"index_count" xml:"index_count"` } -// ToFlatTables converts a Database to a slice of FlatTables +// ToFlatTables converts a Database to a slice of FlatTables for denormalized access to all tables. func (d *Database) ToFlatTables() []*FlatTable { flatTables := make([]*FlatTable, 0) @@ -94,7 +97,7 @@ func (d *Database) ToFlatTables() []*FlatTable { return flatTables } -// FlatConstraint represents a constraint with full context +// FlatConstraint represents a constraint with full database context and resolved references. type FlatConstraint struct { DatabaseName string `json:"database_name" yaml:"database_name" xml:"database_name"` SchemaName string `json:"schema_name" yaml:"schema_name" xml:"schema_name"` @@ -112,7 +115,7 @@ type FlatConstraint struct { OnUpdate string `json:"on_update,omitempty" yaml:"on_update,omitempty" xml:"on_update,omitempty"` } -// ToFlatConstraints converts a Database to a slice of FlatConstraints +// ToFlatConstraints converts a Database to a slice of FlatConstraints for denormalized access to all constraints. func (d *Database) ToFlatConstraints() []*FlatConstraint { flatConstraints := make([]*FlatConstraint, 0) @@ -148,7 +151,7 @@ func (d *Database) ToFlatConstraints() []*FlatConstraint { return flatConstraints } -// FlatRelationship represents a relationship with full context +// FlatRelationship represents a relationship with full database context and fully qualified table names. type FlatRelationship struct { DatabaseName string `json:"database_name" yaml:"database_name" xml:"database_name"` RelationshipName string `json:"relationship_name" yaml:"relationship_name" xml:"relationship_name"` @@ -164,7 +167,7 @@ type FlatRelationship struct { Description string `json:"description,omitempty" yaml:"description,omitempty" xml:"description,omitempty"` } -// ToFlatRelationships converts a Database to a slice of FlatRelationships +// ToFlatRelationships converts a Database to a slice of FlatRelationships for denormalized access to all relationships. func (d *Database) ToFlatRelationships() []*FlatRelationship { flatRelationships := make([]*FlatRelationship, 0) diff --git a/pkg/models/models.go b/pkg/models/models.go index 8868c0b..71037d5 100644 --- a/pkg/models/models.go +++ b/pkg/models/models.go @@ -1,13 +1,19 @@ +// Package models provides the core data structures for representing database schemas. +// It defines types for databases, schemas, tables, columns, relationships, constraints, +// indexes, views, sequences, and other database objects. These models serve as the +// intermediate representation for converting between various database schema formats. package models import "strings" +// DatabaseType represents the type of database system. type DatabaseType string +// Supported database types. const ( - PostgresqlDatabaseType DatabaseType = "pgsql" - MSSQLDatabaseType DatabaseType = "mssql" - SqlLiteDatabaseType DatabaseType = "sqlite" + PostgresqlDatabaseType DatabaseType = "pgsql" // PostgreSQL database + MSSQLDatabaseType DatabaseType = "mssql" // Microsoft SQL Server database + SqlLiteDatabaseType DatabaseType = "sqlite" // SQLite database ) // Database represents the complete database schema @@ -21,11 +27,13 @@ type Database struct { SourceFormat string `json:"source_format,omitempty" yaml:"source_format,omitempty" xml:"source_format,omitempty"` // Source Format of the database. } -// SQLNamer returns the database name in lowercase +// SQLName returns the database name in lowercase for SQL compatibility. func (d *Database) SQLName() string { return strings.ToLower(d.Name) } +// Schema represents a database schema, which is a logical grouping of database objects +// such as tables, views, sequences, and relationships within a database. type Schema struct { Name string `json:"name" yaml:"name" xml:"name"` Description string `json:"description,omitempty" yaml:"description,omitempty" xml:"description,omitempty"` @@ -43,11 +51,13 @@ type Schema struct { Enums []*Enum `json:"enums,omitempty" yaml:"enums,omitempty" xml:"enums"` } -// SQLName returns the schema name in lowercase +// SQLName returns the schema name in lowercase for SQL compatibility. func (d *Schema) SQLName() string { return strings.ToLower(d.Name) } +// Table represents a database table with its columns, constraints, indexes, +// and relationships. Tables are the primary data storage structures in a database. type Table struct { Name string `json:"name" yaml:"name" xml:"name"` Description string `json:"description,omitempty" yaml:"description,omitempty" xml:"description,omitempty"` @@ -63,11 +73,12 @@ type Table struct { RefSchema *Schema `json:"-" yaml:"-" xml:"-"` // Excluded to prevent circular references } -// SQLName returns the table name in lowercase +// SQLName returns the table name in lowercase for SQL compatibility. func (d *Table) SQLName() string { return strings.ToLower(d.Name) } +// GetPrimaryKey returns the primary key column for the table, or nil if none exists. func (m Table) GetPrimaryKey() *Column { for _, column := range m.Columns { if column.IsPrimaryKey { @@ -77,6 +88,7 @@ func (m Table) GetPrimaryKey() *Column { return nil } +// GetForeignKeys returns all foreign key constraints for the table. func (m Table) GetForeignKeys() []*Constraint { keys := make([]*Constraint, 0) @@ -101,7 +113,7 @@ type View struct { RefSchema *Schema `json:"-" yaml:"-" xml:"-"` // Excluded to prevent circular references } -// SQLName returns the view name in lowercase +// SQLName returns the view name in lowercase for SQL compatibility. func (d *View) SQLName() string { return strings.ToLower(d.Name) } @@ -124,7 +136,7 @@ type Sequence struct { RefSchema *Schema `json:"-" yaml:"-" xml:"-"` // Excluded to prevent circular references } -// SQLName returns the sequence name in lowercase +// SQLName returns the sequence name in lowercase for SQL compatibility. func (d *Sequence) SQLName() string { return strings.ToLower(d.Name) } @@ -148,11 +160,13 @@ type Column struct { Sequence uint `json:"sequence,omitempty" yaml:"sequence,omitempty" xml:"sequence,omitempty"` } -// SQLName returns the table name in lowercase +// SQLName returns the column name in lowercase for SQL compatibility. func (d *Column) SQLName() string { return strings.ToLower(d.Name) } +// Index represents a database index for optimizing query performance. +// Indexes can be unique, partial, or include additional columns. type Index struct { Name string `json:"name" yaml:"name" xml:"name"` Description string `json:"description,omitempty" yaml:"description,omitempty" xml:"description,omitempty"` @@ -168,19 +182,23 @@ type Index struct { Sequence uint `json:"sequence,omitempty" yaml:"sequence,omitempty" xml:"sequence,omitempty"` } -// SQLName returns the Indexin lowercase +// SQLName returns the index name in lowercase for SQL compatibility. func (d *Index) SQLName() string { return strings.ToLower(d.Name) } +// RelationType represents the type of relationship between database tables. type RelationType string +// Supported relationship types. const ( - OneToOne RelationType = "one_to_one" - OneToMany RelationType = "one_to_many" - ManyToMany RelationType = "many_to_many" + OneToOne RelationType = "one_to_one" // One record in table A relates to one record in table B + OneToMany RelationType = "one_to_many" // One record in table A relates to many records in table B + ManyToMany RelationType = "many_to_many" // Many records in table A relate to many records in table B ) +// Relationship represents a relationship between two database tables. +// Relationships can be one-to-one, one-to-many, or many-to-many. type Relationship struct { Name string `json:"name" yaml:"name" xml:"name"` Type RelationType `json:"type" yaml:"type" xml:"type"` @@ -198,11 +216,13 @@ type Relationship struct { Sequence uint `json:"sequence,omitempty" yaml:"sequence,omitempty" xml:"sequence,omitempty"` } -// SQLName returns the Relationship lowercase +// SQLName returns the relationship name in lowercase for SQL compatibility. func (d *Relationship) SQLName() string { return strings.ToLower(d.Name) } +// Constraint represents a database constraint that enforces data integrity rules. +// Constraints can be primary keys, foreign keys, unique constraints, check constraints, or not-null constraints. type Constraint struct { Name string `json:"name" yaml:"name" xml:"name"` Type ConstraintType `json:"type" yaml:"type" xml:"type"` @@ -220,30 +240,37 @@ type Constraint struct { Sequence uint `json:"sequence,omitempty" yaml:"sequence,omitempty" xml:"sequence,omitempty"` } +// SQLName returns the constraint name in lowercase for SQL compatibility. func (d *Constraint) SQLName() string { return strings.ToLower(d.Name) } +// ConstraintType represents the type of database constraint. type ConstraintType string +// Enum represents a database enumeration type with a set of allowed values. type Enum struct { Name string `json:"name" yaml:"name" xml:"name"` Values []string `json:"values" yaml:"values" xml:"values"` Schema string `json:"schema,omitempty" yaml:"schema,omitempty" xml:"schema,omitempty"` } +// SQLName returns the enum name in lowercase for SQL compatibility. func (d *Enum) SQLName() string { return strings.ToLower(d.Name) } +// Supported constraint types. const ( - PrimaryKeyConstraint ConstraintType = "primary_key" - ForeignKeyConstraint ConstraintType = "foreign_key" - UniqueConstraint ConstraintType = "unique" - CheckConstraint ConstraintType = "check" - NotNullConstraint ConstraintType = "not_null" + PrimaryKeyConstraint ConstraintType = "primary_key" // Primary key uniquely identifies each record + ForeignKeyConstraint ConstraintType = "foreign_key" // Foreign key references another table + UniqueConstraint ConstraintType = "unique" // Unique constraint ensures all values are different + CheckConstraint ConstraintType = "check" // Check constraint validates data against an expression + NotNullConstraint ConstraintType = "not_null" // Not null constraint requires a value ) +// Script represents a database migration or initialization script. +// Scripts can have dependencies and rollback capabilities. type Script struct { Name string `json:"name" yaml:"name" xml:"name"` Description string `json:"description" yaml:"description" xml:"description"` @@ -256,11 +283,12 @@ type Script struct { Sequence uint `json:"sequence,omitempty" yaml:"sequence,omitempty" xml:"sequence,omitempty"` } +// SQLName returns the script name in lowercase for SQL compatibility. func (d *Script) SQLName() string { return strings.ToLower(d.Name) } -// Initialize functions +// Initialization functions for creating new model instances with proper defaults. // InitDatabase initializes a new Database with empty slices func InitDatabase(name string) *Database { diff --git a/pkg/models/summaryview.go b/pkg/models/summaryview.go index b7b244a..41ad102 100644 --- a/pkg/models/summaryview.go +++ b/pkg/models/summaryview.go @@ -1,10 +1,12 @@ package models -// ============================================================================= -// Summary/Compact Views - Lightweight views with essential fields -// ============================================================================= +// Summary/Compact Views +// +// This file provides lightweight summary structures with essential fields +// and aggregated counts for quick database schema overviews without loading +// full object graphs. -// DatabaseSummary provides a compact overview of a database +// DatabaseSummary provides a compact overview of a database with aggregated statistics. type DatabaseSummary struct { Name string `json:"name" yaml:"name" xml:"name"` Description string `json:"description,omitempty" yaml:"description,omitempty" xml:"description,omitempty"` @@ -15,7 +17,7 @@ type DatabaseSummary struct { TotalColumns int `json:"total_columns" yaml:"total_columns" xml:"total_columns"` } -// ToSummary converts a Database to a DatabaseSummary +// ToSummary converts a Database to a DatabaseSummary with calculated counts. func (d *Database) ToSummary() *DatabaseSummary { summary := &DatabaseSummary{ Name: d.Name, @@ -36,7 +38,7 @@ func (d *Database) ToSummary() *DatabaseSummary { return summary } -// SchemaSummary provides a compact overview of a schema +// SchemaSummary provides a compact overview of a schema with aggregated statistics. type SchemaSummary struct { Name string `json:"name" yaml:"name" xml:"name"` Description string `json:"description,omitempty" yaml:"description,omitempty" xml:"description,omitempty"` @@ -47,7 +49,7 @@ type SchemaSummary struct { TotalConstraints int `json:"total_constraints" yaml:"total_constraints" xml:"total_constraints"` } -// ToSummary converts a Schema to a SchemaSummary +// ToSummary converts a Schema to a SchemaSummary with calculated counts. func (s *Schema) ToSummary() *SchemaSummary { summary := &SchemaSummary{ Name: s.Name, @@ -66,7 +68,7 @@ func (s *Schema) ToSummary() *SchemaSummary { return summary } -// TableSummary provides a compact overview of a table +// TableSummary provides a compact overview of a table with aggregated statistics. type TableSummary struct { Name string `json:"name" yaml:"name" xml:"name"` Schema string `json:"schema" yaml:"schema" xml:"schema"` @@ -79,7 +81,7 @@ type TableSummary struct { ForeignKeyCount int `json:"foreign_key_count" yaml:"foreign_key_count" xml:"foreign_key_count"` } -// ToSummary converts a Table to a TableSummary +// ToSummary converts a Table to a TableSummary with calculated counts. func (t *Table) ToSummary() *TableSummary { summary := &TableSummary{ Name: t.Name,