# SDL3 Parser Documentation

Complete documentation for the SDL3 C header to Zig bindings generator.

## Quick Links

- **[README](../README.md)** - Start here for project overview
- **[Getting Started](GETTING_STARTED.md)** - Installation and first use
- **[API Reference](API_REFERENCE.md)** - Command-line options

## User Guides

### Essential

1. **[Getting Started](GETTING_STARTED.md)** - Installation, first parse, basic usage
2. **[Quickstart Guide](QUICKSTART.md)** - Quick reference for common tasks
3. **[API Reference](API_REFERENCE.md)** - Complete command-line reference

### Features

4. **[Dependency Resolution](DEPENDENCY_RESOLUTION.md)** - How automatic type extraction works
5. **[Known Issues](KNOWN_ISSUES.md)** - Current limitations and workarounds

## Technical Documentation

### Architecture

6. **[Architecture Overview](ARCHITECTURE.md)** - System design and components
7. **[Dependency Flow](DEPENDENCY_FLOW.md)** - Complete technical walkthrough (845 lines)
8. **[Visual Flow Diagrams](VISUAL_FLOW.md)** - Quick reference diagrams

### Implementation Details

9. **[Multi-Field Structs](MULTI_FIELD_IMPLEMENTATION.md)** - How `int x, y;` parsing works
10. **[Typedef Support](TYPEDEF_IMPLEMENTATION.md)** - Simple typedef implementation
11. **[Multi-Header Testing](MULTI_HEADER_TEST_RESULTS.md)** - Test results across SDL headers

## Development

12. **[Development Guide](DEVELOPMENT.md)** - Contributing, extending, Zig 0.15 guidelines
13. **[Roadmap](ROADMAP.md)** - Future plans and priorities

## Quick Start

```bash
# Install
cd parser/
zig build
zig build test

# Generate bindings
zig build run -- ../SDL/include/SDL3/SDL_gpu.h --output=gpu.zig

# Use in code
const gpu = @import("gpu.zig");
```

## Documentation by Use Case

### "I want to generate Zig bindings"
→ Start with [Getting Started](GETTING_STARTED.md)

### "I want to understand how it works"
→ Read [Architecture](ARCHITECTURE.md)

### "I'm hitting an error"
→ Check [Known Issues](KNOWN_ISSUES.md)

### "I want to extend the parser"
→ See [Development Guide](DEVELOPMENT.md)

### "I need technical details"
→ Deep dive: [Dependency Flow](DEPENDENCY_FLOW.md)

## Project Status

**Version**: 2.1  
**Status**: Production ready for SDL_gpu.h  
**Last Updated**: 2026-01-22  

### Supported Headers

| Header | Status | Notes |
|--------|--------|-------|
| SDL_gpu.h | ✅ Complete | 100% dependency resolution |
| SDL_keyboard.h | ⚠️ Partial | Large enum issues |
| SDL_video.h | ⚠️ Partial | Some types not found |
| SDL_events.h | ⚠️ Partial | Parse errors |

See [Known Issues](KNOWN_ISSUES.md) for details.

## Key Features

✅ Automatic dependency resolution (100% for SDL_gpu.h)  
✅ Multi-field struct parsing (`int x, y;`)  
✅ Typedef support (`typedef Uint32 SDL_Type;`)  
✅ Method organization (functions → methods)  
✅ Mock generation for testing  
✅ Comprehensive error reporting  

## Statistics

- **Code**: ~900 lines (production)
- **Tests**: 26+ unit tests (100% passing)
- **Documentation**: 5,500+ lines
- **Success Rate**: 100% for SDL_gpu.h

---

## Archive

Historical planning and session documents are in `archive/` for reference.