# Documentation Standards Contract

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

## Purpose

This contract defines the documentation standards that must be met for the SDK to be considered publish-ready. These standards serve as acceptance criteria for the feature.

## Rustdoc Standards

### Crate-Level Documentation (lib.rs)

```rust
//! # LastID Rust SDK
//!
//! [One paragraph description]
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! // Complete, runnable example
//! ```
//!
//! ## Features
//!
//! - **Feature 1**: Description
//! - **Feature 2**: Description
//!
//! ## Feature Flags
//!
//! | Flag | Default | Description |
//! |------|---------|-------------|
```

### Module Documentation

```rust
//! Brief description of module purpose.
//!
//! ## Overview
//!
//! Longer description if needed.
//!
//! ## Key Types
//!
//! - [`TypeName`] - Brief description
```

### Type Documentation

```rust
/// Brief description of type purpose.
///
/// Longer description with context.
///
/// # Example
///
/// ```rust
/// use lastid_sdk::TypeName;
///
/// let instance = TypeName::new();
/// ```
pub struct TypeName { ... }
```

### Function Documentation

```rust
/// Brief description of what this function does.
///
/// Longer description if behavior is complex.
///
/// # Arguments
///
/// * `arg1` - Description of first argument
/// * `arg2` - Description of second argument
///
/// # Returns
///
/// Description of return value.
///
/// # Errors
///
/// * [`ErrorType::Variant`] - When this error occurs
///
/// # Example
///
/// ```rust
/// // Usage example
/// ```
pub fn function_name(arg1: Type1, arg2: Type2) -> Result<Return, Error> { ... }
```

## External File Standards

### README.md Structure

```markdown
# Crate Name

Brief description.

## Features

- Feature list

## Installation

### Native

```toml
[dependencies]
crate-name = "version"
```

### WASM

```toml
[dependencies]
crate-name = { version = "version", features = ["wasm"] }
```

## Quick Start

```rust
// Complete example
```

## Documentation

Link to docs.rs

## Feature Flags

| Flag | Default | Description |
|------|---------|-------------|

## License

License information

## Contributing

Link to CONTRIBUTING.md
```

### CHANGELOG.md Structure

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security

## [0.1.0] - YYYY-MM-DD

### Added
- Initial release
- Feature 1
- Feature 2
```

### CONTRIBUTING.md Structure

```markdown
# Contributing to LastID Rust SDK

## Code of Conduct

[Reference or include]

## Getting Started

### Prerequisites

- Rust 1.85+
- cargo

### Building

```bash
cargo build --all-features
```

### Testing

```bash
cargo test --all-features
```

## Code Style

- Run `cargo fmt` before committing
- Run `cargo clippy --all-features` and fix all warnings
- Maintain 95% test coverage

## Pull Request Process

1. Create feature branch from `main`
2. Make changes following code style
3. Add tests for new functionality
4. Update documentation for public API changes
5. Run CI checks locally
6. Submit PR with description

## Constitution Compliance

All contributions must comply with the [SDK Constitution](.specify/memory/constitution.md).

Key requirements:
- 95% test coverage
- Zero clippy warnings
- Comprehensive rustdoc
- Cross-platform compatibility
```

## Example Standards

### Example File Structure

```rust
//! Example: [Title]
//!
//! This example demonstrates [what it demonstrates].
//!
//! # Prerequisites
//!
//! - [Prerequisite 1]
//! - [Prerequisite 2]
//!
//! # Running
//!
//! ```bash
//! cargo run --example [example_name] [--features feature1,feature2]
//! ```
//!
//! # What This Example Does
//!
//! 1. Step 1
//! 2. Step 2
//! 3. Step 3

use lastid_sdk::{...};

#[tokio::main]
async fn main() -> Result<(), lastid_sdk::LastIDError> {
    // Step 1: Description
    // [code]

    // Step 2: Description
    // [code]

    // Error handling demonstration
    match result {
        Ok(value) => { ... }
        Err(e) => { ... }
    }

    Ok(())
}
```

## Verification Commands

```bash
# Verify rustdoc builds without warnings
cargo doc --no-deps --all-features

# Verify doc tests pass
cargo test --doc

# Verify examples compile
cargo build --examples

# Verify examples run (manual)
cargo run --example base_credential
```

## Acceptance Criteria

- [ ] `cargo doc --no-deps --all-features` completes with zero warnings
- [ ] `cargo test --doc` passes
- [ ] All examples in `examples/` have proper header documentation
- [ ] README.md exists and follows structure above
- [ ] CHANGELOG.md exists and follows Keep a Changelog format
- [ ] CONTRIBUTING.md exists with clear guidelines
- [ ] No TODO/FIXME/placeholder text in any documentation
