GoDoc

Locky's Go package documentation is generated using standard Go documentation tools.

Viewing GoDoc

GitHub Pages

📖 GoDoc Overview (Links to pkg.go.dev)

Or use the relative link when browsing documentation: 📖 GoDoc Overview

Online - pkg.go.dev (When Published)

Once the package is published, view the official Go documentation online:

📖 View on pkg.go.dev

Local Documentation

Generate and view documentation locally:

# Install godoc tool (if not already installed)
go install golang.org/x/tools/cmd/godoc@latest

# Start local documentation server
godoc -http=:6060

# Open in browser
open http://localhost:6060/pkg/github.com/ryo-arima/locky/

Generated HTML

Pre-generated HTML documentation is available in:

docs/godoc/

Package Structure

Main Packages

Server Packages

Entity Packages

Client Packages

Key Types and Functions

Configuration

// BaseConfig holds application configuration
type BaseConfig struct {
    YamlConfig YamlConfig
    DB         *gorm.DB
}

// LoadConfig loads configuration from YAML file
func LoadConfig(path string) (*BaseConfig, error)

Server

// InitRouter initializes the Gin router with all routes and middleware
func InitRouter(conf config.BaseConfig) *gin.Engine

// Start starts the HTTP server
func Start(router *gin.Engine, port int) error

Repository

// UserRepository provides user data access
type UserRepository interface {
    ListUsers(filters map[string]interface{}) ([]model.User, error)
    GetUser(id uint) (*model.User, error)
    CreateUser(user *model.User) error
    UpdateUser(user *model.User) error
    DeleteUser(id uint) error
}

Entity Models

// User represents a user account
type User struct {
    ID        uint      `gorm:"primaryKey"`
    UUID      string    `gorm:"uniqueIndex"`
    Name      string
    Email     string    `gorm:"uniqueIndex"`
    Password  string
    CreatedAt time.Time
    UpdatedAt time.Time
    DeletedAt *time.Time `gorm:"index"`
}

Documentation Standards

Package Comments

Every package should have a package-level comment:

// Package server implements the HTTP server and routing logic.
//
// The server package provides:
//   - Gin-based HTTP routing
//   - Middleware integration (JWT, Casbin, logging)
//   - Controller initialization
//   - Repository wiring
//
// Example usage:
//
//   config := config.LoadConfig("etc/app.yaml")
//   router := server.InitRouter(config)
//   server.Start(router, 8080)
package server

Function Comments

All exported functions must have documentation:

// ListUsers retrieves a list of users based on the provided filters.
//
// Filters can include:
//   - name: Filter by name (partial match)
//   - email: Filter by email (exact match)
//   - limit: Maximum number of results
//   - offset: Number of results to skip
//
// Returns a slice of User models and an error if the operation fails.
func (r *userRepository) ListUsers(filters map[string]interface{}) ([]model.User, error)

Type Comments

All exported types must be documented:

// User represents a user account in the system.
//
// Users can belong to multiple groups and have various roles
// that determine their permissions within the application.
type User struct {
    ID        uint      `gorm:"primaryKey" json:"id"`
    UUID      string    `gorm:"uniqueIndex" json:"uuid"`
    Name      string    `json:"name"`
    Email     string    `gorm:"uniqueIndex" json:"email"`
    Password  string    `json:"-"` // Never serialize password
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
    DeletedAt *time.Time `gorm:"index" json:"deleted_at,omitempty"`
}

Generating Documentation

Standard godoc

# Generate HTML documentation
godoc -html github.com/ryo-arima/locky > docs/godoc/index.html

# Generate documentation for specific package
godoc -html github.com/ryo-arima/locky/pkg/server > docs/godoc/server.html

pkgsite (Modern godoc)

# Install pkgsite
go install golang.org/x/pkgsite/cmd/pkgsite@latest

# Run local server
pkgsite -http=:6060

# View documentation
open http://localhost:6060/github.com/ryo-arima/locky

Documentation Best Practices

Writing Good Documentation

1. Start with a summary: One-line description of what it does
2. Explain the why: Not just what, but why it exists
3. Provide examples: Show common usage patterns
4. Document parameters: Explain each parameter's purpose
5. Document return values: Explain what's returned and when
6. Document errors: List possible error conditions
7. Link related items: Reference related types/functions

Example Structure

// FunctionName does something specific.
//
// More detailed explanation of what the function does,
// why it exists, and how it should be used.
//
// Parameters:
//   - param1: Description of first parameter
//   - param2: Description of second parameter
//
// Returns:
//   - result: Description of return value
//   - error: Possible error conditions
//
// Example:
//
//   result, err := FunctionName(arg1, arg2)
//   if err != nil {
//       log.Fatal(err)
//   }
//   fmt.Println(result)
func FunctionName(param1 string, param2 int) (result string, err error)

Package Dependencies

View package dependencies:

# Generate dependency graph
go mod graph

# Visualize with graphviz
go mod graph | dot -Tsvg -o docs/dependencies.svg

Code Examples in Documentation

GoDoc supports executable examples:

// Example_listUsers demonstrates how to list users
func Example_listUsers() {
    config := config.LoadConfig("etc/app.yaml")
    repo := repository.NewUserRepository(config)
    
    users, err := repo.ListUsers(map[string]interface{}{
        "limit": 10,
    })
    if err != nil {
        log.Fatal(err)
    }
    
    for _, user := range users {
        fmt.Println(user.Name)
    }
}

Testing Documentation

Verify documentation builds correctly:

# Check for documentation issues
go vet ./...

# Run documentation tests
go test -v ./...

Next Steps

• Swagger Documentation
• API Reference
• Contributing