169 lines
6.7 KiB
Markdown
169 lines
6.7 KiB
Markdown
---
|
|
description: Generate comprehensive YAML documentation from Go struct definitions with sensible default values
|
|
argument-hint: [file:StructName] [output.md]
|
|
---
|
|
|
|
## Name
|
|
yaml:docs
|
|
|
|
## Synopsis
|
|
```
|
|
/yaml:docs [file:StructName] [output.md]
|
|
```
|
|
|
|
## Description
|
|
The `yaml:docs` command generates comprehensive YAML documentation from Go struct definitions. It analyzes Go structs and produces complete, well-documented YAML configuration examples with intelligent default values for all fields.
|
|
|
|
This command is designed to help developers quickly create YAML configuration documentation by:
|
|
- Automatically generating sensible default values for all struct fields
|
|
- Adding inline comments explaining each field's purpose and constraints
|
|
- Maintaining proper YAML formatting and structure
|
|
- Supporting nested structs, slices, maps, and complex types
|
|
- Respecting struct tags (yaml, json, validate, default)
|
|
|
|
The spec sections is inspired by https://man7.org/linux/man-pages/man7/man-pages.7.html#top_of_page
|
|
|
|
## Implementation
|
|
|
|
You are a specialized tool for generating comprehensive YAML documentation from Go struct definitions.
|
|
|
|
### Task
|
|
|
|
Analyze the provided Go struct and generate complete YAML documentation with:
|
|
- All fields populated with intelligent, sensible default values (never leave fields empty)
|
|
- Inline comments explaining each field's purpose and constraints
|
|
- Proper YAML formatting and structure
|
|
- Nested YAML for embedded structs with all sub-fields populated
|
|
|
|
### Input Handling
|
|
|
|
The user may provide input in these formats:
|
|
1. `$1 $2` - File path with struct name (e.g., `pkg/api/types.go:MetricsConfig`) and optional output file path
|
|
2. `$1` - Just the file path with struct name
|
|
3. Selected code containing a Go struct definition (no arguments)
|
|
|
|
### Instructions
|
|
|
|
1. **Locate the struct:**
|
|
- If a file path is provided (format: `file.go:StructName`), read that file and find the specified struct
|
|
- If code is selected, use the selected Go struct definition
|
|
- Search for the struct definition and any embedded struct types
|
|
|
|
2. **Analyze struct metadata:**
|
|
- Examine struct tags: `yaml`, `json`, `validate`, `default`
|
|
- Note validation constraints (min, max, required, etc.)
|
|
- Identify field types (strings, ints, bools, slices, maps, nested structs, pointers)
|
|
- Preserve field ordering from the struct definition
|
|
|
|
3. **Generate intelligent defaults:**
|
|
- **Strings**: Use contextually appropriate values based on field names (e.g., "localhost" for host, "info" for log level)
|
|
- **Integers**: Use common sensible values (e.g., 8080 for port, 30 for timeout seconds)
|
|
- **Booleans**: Default to `false` unless the field name suggests otherwise
|
|
- **Durations**: Use human-readable format (e.g., "30s", "5m", "1h")
|
|
- **Slices**: Provide 1-2 example values in array format
|
|
- **Maps**: Provide 1-2 example key-value pairs
|
|
- **Nested structs**: Recursively populate all sub-fields
|
|
- **Pointers**: Treat as optional but still provide example values
|
|
|
|
4. **Format the output:**
|
|
- Use proper YAML indentation (2 spaces)
|
|
- Add inline comments with `#` explaining each field
|
|
- Include validation constraints in comments where applicable
|
|
- Add section headers for major struct groups
|
|
- Ensure valid YAML syntax
|
|
|
|
5. **Write the output:**
|
|
- If an output file path is provided as `$2`, use the Write tool to create that file with the generated YAML content (write pure YAML, not markdown)
|
|
- Otherwise, display the generated YAML to the user in a markdown code block with yaml syntax highlighting
|
|
|
|
### Important Behaviors
|
|
|
|
- **ALWAYS populate all fields** - never leave fields empty or use placeholder text
|
|
- Infer contextually appropriate defaults from field names and types
|
|
- Include helpful comments explaining what each field does
|
|
- Maintain the struct's field order in the YAML output
|
|
- Handle complex nested structures by recursively applying these rules
|
|
|
|
## Return Value
|
|
- **Claude agent text**: Generated YAML documentation with intelligent defaults and inline comments
|
|
- **File output** (if $2 provided): YAML file written to the specified path
|
|
|
|
## Examples
|
|
|
|
### Example 1: Basic usage with file path and struct name
|
|
```
|
|
/yaml:docs pkg/config/server.go:ServerConfig
|
|
```
|
|
|
|
Input struct:
|
|
```go
|
|
type ServerConfig struct {
|
|
Host string `yaml:"host" json:"host" validate:"required"`
|
|
Port int `yaml:"port" json:"port" validate:"min=1,max=65535"`
|
|
Timeout time.Duration `yaml:"timeout" json:"timeout"`
|
|
Debug bool `yaml:"debug" json:"debug"`
|
|
Features []string `yaml:"features" json:"features"`
|
|
}
|
|
```
|
|
|
|
Output:
|
|
```yaml
|
|
# Server configuration
|
|
host: "localhost" # Required: Server hostname or IP address
|
|
port: 8080 # Port number (1-65535)
|
|
timeout: "30s" # Request timeout duration
|
|
debug: false # Enable debug logging
|
|
features: ["metrics", "tracing"] # List of enabled features
|
|
```
|
|
|
|
### Example 2: Complex nested structs with output file
|
|
```
|
|
/yaml:docs pkg/config/database.go:DatabaseConfig config/database.yaml
|
|
```
|
|
|
|
Input struct:
|
|
```go
|
|
type DatabaseConfig struct {
|
|
Host string `yaml:"host"`
|
|
Port int `yaml:"port"`
|
|
SSL SSLConfig `yaml:"ssl"`
|
|
Pools map[string]int `yaml:"pools"`
|
|
Metadata *MetadataConfig `yaml:"metadata,omitempty"`
|
|
}
|
|
|
|
type SSLConfig struct {
|
|
Enabled bool `yaml:"enabled"`
|
|
CertFile string `yaml:"cert_file"`
|
|
KeyFile string `yaml:"key_file"`
|
|
}
|
|
```
|
|
|
|
Generated YAML (written to config/database.yaml):
|
|
```yaml
|
|
# Database configuration
|
|
host: "localhost" # Database host
|
|
port: 5432 # Database port
|
|
ssl: # SSL configuration
|
|
enabled: true # Enable SSL connection
|
|
cert_file: "/etc/ssl/certs/db.crt" # SSL certificate file path
|
|
key_file: "/etc/ssl/private/db.key" # SSL private key file path
|
|
pools: # Connection pools configuration
|
|
read: 10 # Read connection pool size
|
|
write: 5 # Write connection pool size
|
|
metadata: # Optional metadata configuration
|
|
cache_ttl: "1h" # Cache time-to-live
|
|
sync_interval: "5m" # Sync interval
|
|
```
|
|
|
|
### Example 3: Using with selected code
|
|
Select a Go struct definition in your editor, then run:
|
|
```
|
|
/yaml:docs
|
|
```
|
|
|
|
The command will generate YAML documentation from the selected struct.
|
|
|
|
## Arguments
|
|
- $1: File path and struct name in format `file.go:StructName` (e.g., `pkg/api/types.go:MetricsConfig`), or selected code containing a Go struct definition
|
|
- $2: (Optional) Output file path where the generated YAML will be written (e.g., `config/example.yaml`)
|