# Examples Index
Quick reference for `waddling-errors-macros` examples.
---
## ⚙️ Feature Flags Required
Most examples require specific feature flags to compile and run. Use the feature combinations shown below:
### Common Feature Combinations
| `--features metadata` | Basic examples without doc generation |
| `--features metadata,doc-gen` | Examples that generate docs |
| `--features metadata,doc-gen,auto-register` | Examples with auto-registration |
| `--features metadata,doc-gen,auto-register,hash` | Full-featured examples with hash generation |
| `--all-features` | Run any example with all features enabled |
### Why Features Are Required
The `metadata` feature is required by most examples because the `DiagnosticRuntime` struct includes gated fields that are only compiled when this feature is enabled:
- `hints_runtime_gated`
- `hints_both_gated`
- `tags_gated`
- `related_codes_gated`
Without the `metadata` feature, the macro-generated code won't match the struct definition.
**Quick tip:** When in doubt, use `--all-features` to run any example:
```bash
cargo run --example EXAMPLE_NAME --all-features
```
---
## 🚀 Available Examples
### 1. Complete System Reference ⭐ Start Here!
**Directory:** `complete_system/`
**Time:** 30-45 minutes
**Features:** Everything! Full 6-component system
Comprehensive reference implementation showing all features working together:
- 6 complete components (Auth, Database, API, Cache, Queue, Storage)
- Primary categories and sequence conventions
- Auto-registration with `<json, html>`
- Role-based documentation generation
- Component locations with security
```bash
cargo run --example complete_system --features metadata,doc-gen,auto-register
```
**What you'll learn:**
- Complete component structure
- Auto-registration with `<json, html>`
- Role-based documentation
- Component locations
**Structure:**
```
complete_system/
├── main.rs # Entry point and doc generation
├── components/ # 6 full components
│ ├── auth.rs
│ ├── database.rs
│ ├── api.rs
│ ├── cache.rs
│ ├── queue.rs
│ └── storage.rs
├── primaries/mod.rs # Primary categories
└── sequences.rs # Sequence conventions
```
---
### 2. Component Location Security 🛡️
**File:** `component_location_security.rs`
**Time:** 15-20 minutes
**Features:** Role-based security, secure by default, Public/Developer/Internal roles
Comprehensive security showcase demonstrating how to control component location visibility in documentation.
```bash
cargo run --example component_location_security --features metadata,doc-gen
```
**What you'll learn:**
- Public locations (safe for everyone)
- Developer locations (for contributors)
- Internal locations (team only, default)
- How documentation filters by role
- Security best practices
**Key Concepts:**
- ✅ Secure by default - locations default to Internal
- ✅ Explicit public marking required
- ✅ Prevents information disclosure attacks
---
### 2b. In-Component Documentation Generation 🧪
**File:** `in_component_doc_generation.rs`
**Time:** 5 minutes
**Features:** End-to-end testing, JSON verification, regression prevention
A test/example that verifies `#[in_component]` works correctly all the way from macro to JSON output. Use this as a regression test when making changes to the macro.
```bash
cargo run --example in_component_doc_generation --features metadata,doc-gen
```
**What you'll learn:**
- How `#[in_component]` generates `__COMPONENT` constants
- Component name normalization (uppercase to match `diag!`)
- How to register component locations with `__register_component_location()`
- Role-based filtering in generated JSON
**Key Verifications:**
- ✅ Component names are uppercased (Auth → AUTH)
- ✅ Locations appear in JSON output for correct components
- ✅ Role filtering works (Public/Developer/Internal)
---
### 2c. Component Location Standalone 📍 NEW!
**File:** `component_location_standalone.rs`
**Time:** 10 minutes
**Features:** Multiple components per file, flexible location marking, no module wrapping
Demonstrates the new `component_location!` macro - a standalone alternative to `#[in_component]` that allows multiple component locations in a single file without needing to wrap code in modules.
```bash
cargo run --example component_location_standalone --features metadata,doc-gen
```
**What you'll learn:**
- Register multiple components in ONE file
- Mark locations without `#[in_component]` on modules
- Access marker modules: `__component_loc_<name>::*`
- Combine with `#[in_component]` for flexibility
**Key Features:**
- ✅ `component_location!(Auth)` - minimal syntax
- ✅ `component_location!(Auth, role = public)` - with role
- ✅ Multiple calls per file (no conflicts)
- ✅ Access via `__component_loc_auth::COMPONENT`, `::FILE`, `::ROLE`
- ✅ Register with `__component_loc_auth::register(&mut registry)`
**When to use:**
- Files containing code for multiple components
- When you can't use `#[in_component]` on a module
- Folder-level markers in `mod.rs`
- More granular control than module-level attributes
---
### 3. Custom XML Renderer 🎨
**File:** `custom_xml_renderer.rs`
**Time:** 15-20 minutes
**Features:** Custom renderer implementation, `<json, xml>` auto-registration, extensibility
Learn how to create your own custom renderer (XML, YAML, Markdown, etc.) and integrate it with the auto-registration system.
```bash
cargo run --example custom_xml_renderer --features metadata,doc-gen,auto-register
```
**What you'll learn:**
- How to implement the `Renderer` trait
- Using `<json, xml>` format specifiers with custom formats
- How auto-discovery works with custom renderers
- Role-based rendering for custom formats
- Generating XML output from diagnostics
**Key Concepts:**
- ✅ Custom renderers are first-class citizens
- ✅ Use `<myformat>` in `diag!` macro
- ✅ The format name matches your renderer's `format_name()`
- ✅ Auto-registration works with any custom renderer
---
## 📋 Recommended Learning Path
**For new users:**
1. **`complete_system/`** (45 min) → See everything in action, get the big picture
2. **`component_location_security.rs`** (20 min) → Master security and component locations
3. **`custom_xml_renderer.rs`** (20 min) → Learn extensibility with custom renderers
**Total learning time: ~85 minutes to full proficiency!**
---
## 🔧 Running Examples
### Basic Run
```bash
cargo run --example <name>
```
### With All Features
```bash
cargo run --example <name> --features metadata,doc-gen,auto-register
```
### Build All Examples
```bash
cargo build --examples --all-features
```
---
## 📁 Example File Organization
```
examples/
├── README.md # This file
├── complete_system/ # ⭐ Comprehensive reference (start here!)
│ ├── main.rs
│ ├── components/ # 6 complete components
│ ├── primaries/mod.rs # Primary categories
│ └── sequences.rs # Sequence conventions
├── component_location_security.rs # 🛡️ Security showcase & component tracking
├── component_location_standalone.rs # 📍 NEW! Multiple components per file
├── in_component_doc_generation.rs # 🧪 Regression test for #[in_component]
└── custom_xml_renderer.rs # 🎨 Custom renderer example
```
---
## 💡 Key Features Demonstrated
### In `complete_system/`
- ✅ `component!` macro - Define components with metadata
- ✅ `primary!` macro - Define error categories
- ✅ `sequence!` macro - Define sequence number conventions
- ✅ `diag!` macro - Define error codes with rich metadata
- ✅ Auto-registration with `<json, html>`
- ✅ Role-based documentation (`'CR 'Pub`, `'CR 'Dev`, `'CR 'Int`)
- ✅ Documentation generation (HTML + JSON)
- ✅ Component location tracking
### In `component_location_security.rs`
- ✅ `#[in_component]` attribute with role parameters
- ✅ Public/Developer/Internal role hierarchy
- ✅ Secure by default behavior
- ✅ Role-filtered documentation outputs
- ✅ Security best practices
- ✅ Realistic use cases for each role
### In `custom_xml_renderer.rs`
- ✅ Custom `Renderer` trait implementation
- ✅ XML generation from diagnostics
- ✅ `<json, xml>` format specifiers
- ✅ Auto-registration with custom formats
- ✅ Extensibility pattern for any format (YAML, Markdown, CSV, etc.)
---
## 🆘 Troubleshooting
### "feature not enabled" errors
Add required features:
```bash
--features metadata,doc-gen,auto-register
```
### Examples don't build
Try cleaning and rebuilding:
```bash
cargo clean
cargo build --examples --all-features
```
### Missing output files
Generated documentation appears in `target/doc/` after running examples with `--features doc-gen`:
```
target/doc/
├── ProjectName-pub.html # Public documentation
├── ProjectName-dev.html # Developer documentation
├── ProjectName-int.html # Internal documentation
└── (same for .json files)
```
---
## 🎯 What to Copy for Your Project
All examples use realistic patterns you can copy directly:
**From `complete_system/`:**
- Component structure and organization
- Error code naming conventions
- Role-based hints and descriptions
- Auto-registration setup
**From `component_location_security.rs`:**
- Basic and advanced `#[in_component]` usage
- How to organize code by component
- Security patterns (public vs internal)
- How to mark different module roles
- Documentation generation with role filtering
**From `custom_xml_renderer.rs`:**
- How to implement custom renderers
- Using format specifiers in `diag!` macro
- Integrating with auto-registration system
---
## 📚 Further Reading
- **Syntax Guide:** See `SYNTAX_GUIDE.md` in workspace root
- **Quick Start:** See `SYNTAX_QUICK_START.md` in workspace root
- **Component Roles:** See `docs/COMPONENT_LOCATION_ROLES.md`
- **Main README:** See workspace root for full documentation
---
**Need help?** Check the main workspace README or open an issue!