# Documentation Guide for hyperscan-tokio
This guide covers the documentation available for hyperscan-tokio and how to generate and use it.
## Documentation Types
### 1. API Documentation (rustdoc)
Generate the full API documentation:
```bash
# Generate docs with all features
cargo doc --all-features --open
# Generate docs for docs.rs
cargo doc --all-features --no-deps
```
The documentation includes:
- Comprehensive module documentation
- Examples for all major features
- Safety documentation for unsafe code
- Cross-references between related types
### 2. User Guides
- **[README.md](README.md)** - Quick start and overview
- **[MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)** - Migrating from rust-hyperscan
- **[FEATURE_COMPARISON.md](FEATURE_COMPARISON.md)** - Feature comparison with other libraries
- **[PRODUCTION_CHECKLIST.md](PRODUCTION_CHECKLIST.md)** - Production deployment guide
### 3. Examples
The `examples/` directory contains practical examples:
- **`cpu_features.rs`** - Detecting CPU features and optimization
- **`allocator_comparison.rs`** - Comparing memory allocators
- **`feature_parity.rs`** - Demonstrating feature compatibility
- **`complete_features.rs`** - Comprehensive feature showcase
- **`threat_detection_platform.rs`** - Real-world security use case
- **`metrics_monitoring.rs`** - Metrics and observability
Run examples with:
```bash
cargo run --example metrics_monitoring --features metrics
```
### 4. Architecture Documentation
Key architectural documents:
- **Module structure** - See module-level documentation in source files
- **Safety invariants** - Documented in `hyperscan-tokio-sys/src/lib.rs`
- **Performance notes** - See benchmark documentation
## Documentation Features
### Safety Documentation
All unsafe code is documented with safety invariants:
```rust
// SAFETY: FFI call requirements
// - All pointers in pattern_ptrs are valid CStrings
// - All pointers in ext_ptrs are valid heap allocations
// - flag_values and ids are valid slices with matching length
unsafe {
hs_compile_ext_multi(/* ... */)
}
```
### Feature Gates
Features are documented with `#[cfg_attr(docsrs, doc(cfg(feature = "...")))]`:
```rust
/// Chimera - PCRE-compatible pattern matching with capture groups
#[cfg(feature = "chimera")]
#[cfg_attr(docsrs, doc(cfg(feature = "chimera")))]
pub mod chimera;
```
### Examples in Documentation
Most public APIs include inline examples:
```rust
/// Scanner for performing pattern matching
///
/// # Example
///
/// ```rust
/// use hyperscan_tokio::prelude::*;
///
/// let scanner = Scanner::new(database)?;
/// let matches = scanner.scan_bytes(b"test").await?;
/// ```
pub struct Scanner { /* ... */ }
```
## Generating Documentation
### Local Documentation
```bash
# Full documentation with private items
cargo doc --all-features --document-private-items --open
# Documentation for publishing
cargo doc --all-features --no-deps
```
### Documentation Testing
```bash
# Test all documentation examples
cargo test --doc --all-features
# Test specific module docs
cargo test --doc scanner
```
### Publishing to docs.rs
The crate is configured for optimal docs.rs rendering:
```toml
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
```
## Documentation Standards
### Module Documentation
Every module should have:
1. Brief description
2. Use cases
3. Example code
4. Links to related modules
### Function Documentation
Every public function should have:
1. Brief description
2. Arguments documentation
3. Return value documentation
4. Error conditions
5. Example usage
6. Safety requirements (if applicable)
### Type Documentation
Every public type should have:
1. Purpose and use case
2. Field documentation
3. Implementation notes
4. Example construction and usage
## Contributing Documentation
When contributing:
1. **Add examples** - Every new feature needs an example
2. **Document safety** - Every unsafe block needs a SAFETY comment
3. **Update guides** - Keep migration and feature guides current
4. **Test examples** - Ensure all examples compile and run
5. **Cross-reference** - Link related types and functions
## Documentation TODO
- [ ] Add performance tuning guide
- [ ] Create troubleshooting guide
- [ ] Add more real-world examples
- [ ] Create video tutorials
- [ ] Improve Chimera documentation