relspecgo/GODOC.md

RelSpec API Documentation (godoc)

This document explains how to access and use the RelSpec API documentation.

Viewing Documentation Locally

Using go doc Command Line

View package documentation:

# Main package overview
go doc

# Specific package
go doc ./pkg/models
go doc ./pkg/readers
go doc ./pkg/writers
go doc ./pkg/ui

# Specific type or function
go doc ./pkg/models Database
go doc ./pkg/readers Reader
go doc ./pkg/writers Writer

View all documentation for a package:

go doc -all ./pkg/models
go doc -all ./pkg/readers
go doc -all ./pkg/writers

Using godoc Web Server

Quick Start (Recommended):

make godoc

This will automatically install godoc if needed and start the server on port 6060.

Manual Installation:

go install golang.org/x/tools/cmd/godoc@latest
godoc -http=:6060

Then open your browser to:

http://localhost:6060/pkg/git.warky.dev/wdevs/relspecgo/

Package Documentation

Core Packages

• pkg/models - Core data structures (Database, Schema, Table, Column, etc.)
• pkg/readers - Input format readers (dbml, pgsql, gorm, prisma, etc.)
• pkg/writers - Output format writers (dbml, pgsql, gorm, prisma, etc.)

Utility Packages

• pkg/diff - Schema comparison and difference detection
• pkg/merge - Schema merging utilities
• pkg/transform - Validation and normalization
• pkg/ui - Interactive terminal UI for schema editing

Support Packages

• pkg/pgsql - PostgreSQL-specific utilities
• pkg/inspector - Database introspection capabilities
• pkg/reflectutil - Reflection utilities for Go code analysis
• pkg/commontypes - Shared type definitions

Reader Implementations

Each reader is in its own subpackage under pkg/readers/:

• pkg/readers/dbml - DBML format reader
• pkg/readers/dctx - DCTX format reader
• pkg/readers/drawdb - DrawDB JSON reader
• pkg/readers/graphql - GraphQL schema reader
• pkg/readers/json - JSON schema reader
• pkg/readers/yaml - YAML schema reader
• pkg/readers/gorm - Go GORM models reader
• pkg/readers/bun - Go Bun models reader
• pkg/readers/drizzle - TypeScript Drizzle ORM reader
• pkg/readers/prisma - Prisma schema reader
• pkg/readers/typeorm - TypeScript TypeORM reader
• pkg/readers/pgsql - PostgreSQL database reader
• pkg/readers/sqlite - SQLite database reader

Writer Implementations

Each writer is in its own subpackage under pkg/writers/:

• pkg/writers/dbml - DBML format writer
• pkg/writers/dctx - DCTX format writer
• pkg/writers/drawdb - DrawDB JSON writer
• pkg/writers/graphql - GraphQL schema writer
• pkg/writers/json - JSON schema writer
• pkg/writers/yaml - YAML schema writer
• pkg/writers/gorm - Go GORM models writer
• pkg/writers/bun - Go Bun models writer
• pkg/writers/drizzle - TypeScript Drizzle ORM writer
• pkg/writers/prisma - Prisma schema writer
• pkg/writers/typeorm - TypeScript TypeORM writer
• pkg/writers/pgsql - PostgreSQL SQL writer
• pkg/writers/sqlite - SQLite SQL writer

Usage Examples

Reading a Schema

import (
    "git.warky.dev/wdevs/relspecgo/pkg/readers"
    "git.warky.dev/wdevs/relspecgo/pkg/readers/dbml"
)

reader := dbml.NewReader(&readers.ReaderOptions{
    FilePath: "schema.dbml",
})
db, err := reader.ReadDatabase()

Writing a Schema

import (
    "git.warky.dev/wdevs/relspecgo/pkg/writers"
    "git.warky.dev/wdevs/relspecgo/pkg/writers/gorm"
)

writer := gorm.NewWriter(&writers.WriterOptions{
    OutputPath:  "./models",
    PackageName: "models",
})
err := writer.WriteDatabase(db)

Comparing Schemas

import "git.warky.dev/wdevs/relspecgo/pkg/diff"

result := diff.CompareDatabases(sourceDB, targetDB)
err := diff.FormatDiff(result, diff.OutputFormatText, os.Stdout)

Merging Schemas

import "git.warky.dev/wdevs/relspecgo/pkg/merge"

result := merge.MergeDatabases(targetDB, sourceDB, nil)
fmt.Printf("Added %d tables\n", result.TablesAdded)

Documentation Standards

All public APIs follow Go documentation conventions:

• Package documentation in doc.go files
• Type, function, and method comments start with the item name
• Examples where applicable
• Clear description of parameters and return values
• Usage notes and caveats where relevant

Generating Documentation

To regenerate documentation after code changes:

# Verify documentation builds correctly
go doc -all ./pkg/... > /dev/null

# Check for undocumented exports
go vet ./...

Contributing Documentation

When adding new packages or exported items:

1. Add package documentation in a doc.go file
2. Document all exported types, functions, and methods
3. Include usage examples for complex APIs
4. Follow Go documentation style guide
5. Verify with go doc before committing

References

• Go Documentation Guide
• Effective Go - Commentary
• godoc Documentation