# Data Model: SDK Publish-Ready Documentation

**Date**: 2026-01-17
**Feature**: 001-sdk-publish-ready

## Overview

This feature is documentation-focused. The "data model" describes the documentation artifacts and their relationships rather than runtime data structures.

## Documentation Artifacts

### 1. Rustdoc Documentation

**Location**: Inline in source files

| Artifact Type | Format | Purpose |
|--------------|--------|---------|
| Crate docs | `//!` in lib.rs | SDK overview, quick start, feature list |
| Module docs | `//!` in mod.rs | Module purpose, contained types |
| Type docs | `///` on structs/enums | Type purpose, fields, usage |
| Method docs | `///` on impl blocks | Function behavior, args, errors, examples |
| Trait docs | `///` on trait definitions | Contract description, implementor guidance |

**Quality Criteria**:
- Every public item has at least one descriptive sentence
- Complex types include `# Example` sections
- Functions that can fail document `# Errors` section
- All code examples compile (`cargo test --doc`)

### 2. External Documentation Files

| File | Format | Purpose |
|------|--------|---------|
| README.md | Markdown | Crate overview, installation, quick start |
| CHANGELOG.md | Keep a Changelog | Version history, breaking changes |
| CONTRIBUTING.md | Markdown | Contribution guidelines, code style |

### 3. Example Files

**Location**: `examples/` directory

| Example | Policy Type | Demonstrates |
|---------|-------------|--------------|
| base_credential.rs | BaseCredentialPolicy | Basic flow |
| persona_credential.rs | PersonaPolicy | Field selection |
| verified_email_credential.rs | VerifiedEmailPolicy | Domain constraints |
| verified_phone_credential.rs | VerifiedPhonePolicy | Phone verification |
| employment_verification.rs | EmploymentPolicy | Status/field filtering |
| trust_credential.rs | TrustPolicy | Trust levels |
| age_verification.rs | AgeProofPolicy | Age comparisons |
| config_loading.rs | N/A | Configuration methods |
| poll_and_verify.rs | N/A | Polling loop, verification |

**Quality Criteria**:
- Each example has `//!` header with purpose and run instructions
- Examples are self-contained (copy-paste ready)
- Examples demonstrate error handling, not just happy path
- Examples compile with `cargo build --examples`

## State Machine: Documentation Quality

```
┌─────────────┐    audit     ┌─────────────┐
│   Draft     │──────────────▶│  Reviewed   │
└─────────────┘              └──────┬──────┘
                                    │
                                    │ fix issues
                                    ▼
                             ┌─────────────┐
                             │   Fixed     │
                             └──────┬──────┘
                                    │
                                    │ verify
                                    ▼
                             ┌─────────────┐
                             │  Verified   │
                             └──────┬──────┘
                                    │
                                    │ publish
                                    ▼
                             ┌─────────────┐
                             │  Published  │
                             └─────────────┘
```

## Validation Rules

### Rustdoc Validation

- `cargo doc --no-deps --all-features` must complete with zero warnings
- All intra-doc links must resolve
- Code examples must compile (enforced by `cargo test --doc`)

### README Validation

- All code snippets must be valid Rust syntax
- Feature flag table must match Cargo.toml
- Installation instructions must work for new projects

### CHANGELOG Validation

- Follow Keep a Changelog format
- Include `[Unreleased]` section at top
- Group changes by: Added, Changed, Deprecated, Removed, Fixed, Security

### CONTRIBUTING Validation

- Include code style requirements
- Reference constitution principles
- Explain PR process and CI requirements

## Relationships

```
┌─────────────────────────────────────────────────────────────────┐
│                         Crate (lastid-sdk)                       │
├─────────────────────────────────────────────────────────────────┤
│  lib.rs (crate docs)                                            │
│    ├── Quick Start code example                                 │
│    ├── Feature list                                             │
│    └── Links to modules                                         │
├─────────────────────────────────────────────────────────────────┤
│  modules (mod.rs docs)                                          │
│    ├── client/ → ClientBuilder, LastIDClient                    │
│    ├── policies/ → 8 policy types                               │
│    ├── types/ → RequestId, RequestStatus, VerifiedCredential    │
│    ├── error.rs → LastIDError, HttpError                        │
│    └── config/ → SDKConfig, PollingConfig, etc.                 │
├─────────────────────────────────────────────────────────────────┤
│  examples/                                                       │
│    └── Demonstrate each module's primary use case               │
├─────────────────────────────────────────────────────────────────┤
│  README.md → High-level overview, points to docs.rs             │
│  CHANGELOG.md → Version history                                  │
│  CONTRIBUTING.md → How to contribute                            │
└─────────────────────────────────────────────────────────────────┘
```
