From b34b7dd2e6026c7fb94b32c828fc2c4c0b434543 Mon Sep 17 00:00:00 2001
From: MattJackson <1085847+MattJackson@users.noreply.github.com>
Date: Mon, 6 Apr 2026 15:58:32 -0700
Subject: [PATCH] Improve API docs, add docs.rs badge + link

---
 README.md  |  5 +++-
 src/lib.rs | 80 ++++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 61 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 043a5f8..497b092 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,13 @@
 [![Crates.io](https://img.shields.io/crates/v/libfreemkv)](https://crates.io/crates/libfreemkv)
+[![docs.rs](https://img.shields.io/docsrs/libfreemkv)](https://docs.rs/libfreemkv)
 [![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
 [![Drives: 206](https://img.shields.io/badge/drives-206-brightgreen)]()
 
 # libfreemkv
 
-Rust library for raw sector access on optical drives. Identifies drives using standard SCSI commands, matches them against 206 bundled profiles, and unlocks raw read mode. No external files, no configuration.
+Rust library for 4K UHD / Blu-ray / DVD optical drives. Drive access, disc format parsing, and raw sector reading in one crate. 206 bundled drive profiles.
+
+**[API Documentation](https://docs.rs/libfreemkv)**
 
 Part of the [freemkv](https://github.com/freemkv) project.
 
diff --git a/src/lib.rs b/src/lib.rs
index dba43a4..84c4bd5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,38 +1,72 @@
-//! libfreemkv — Open source raw disc access for optical drives.
+//! libfreemkv — Open source optical drive library for 4K UHD / Blu-ray / DVD.
 //!
-//! Provides SCSI/MMC commands to enable raw reading mode on compatible
-//! Blu-ray drives, allowing direct sector access for disc archival
-//! and backup purposes.
+//! Drive access, disc format parsing, and raw sector reading in one library.
+//! 206 bundled drive profiles. No external files, no configuration.
 //!
-//! # Architecture
-//!
-//! The library is data-driven. Drive-specific SCSI command sequences
-//! are stored in profile files, not in code. Adding support for a new
-//! drive requires only a profile contribution — no rebuild needed.
-//!
-//! ```text
-//! DriveSession (high-level API)
-//!   ├── Platform trait (per-chipset unlock logic)
-//!   ├── DriveProfile (per-drive data from JSON profiles)
-//!   └── ScsiTransport (SG_IO on Linux, IOKit on macOS)
-//! ```
-//!
-//! # Quick Start
+//! # Drive Access
 //!
 //! ```no_run
 //! use libfreemkv::DriveSession;
 //! use std::path::Path;
 //!
-//! let mut session = DriveSession::open(
-//!     Path::new("/dev/sr0"),
-//! ).unwrap();
+//! // Open drive — profiles are bundled, auto-identify
+//! let mut session = DriveSession::open(Path::new("/dev/sr0")).unwrap();
 //!
+//! // Drive identity
+//! println!("{} {}", session.drive_id.vendor_id.trim(), session.drive_id.product_id.trim());
+//!
+//! // Unlock and read raw sectors
 //! session.unlock().unwrap();
 //! session.calibrate().unwrap();
-//!
 //! let mut buf = vec![0u8; 2048];
-//! let n = session.read_sectors(0, 1, &mut buf).unwrap();
+//! session.read_sectors(0, 1, &mut buf).unwrap();
 //! ```
+//!
+//! # Disc Scanning
+//!
+//! ```no_run
+//! # use libfreemkv::{DriveSession, Disc, Title, Stream, StreamKind};
+//! # use std::path::Path;
+//! # let mut session = DriveSession::open(Path::new("/dev/sr0")).unwrap();
+//! // Scan disc structure — UDF filesystem, MPLS playlists, CLPI clip info
+//! // (API in progress — Disc::scan() coming soon)
+//!
+//! // Each title has typed streams:
+//! // stream.codec    → Codec::Hevc / Codec::TrueHd / Codec::Ac3 / Codec::Pgs
+//! // stream.pid      → 0x1100
+//! // stream.language  → "eng"
+//! // stream.hdr      → HdrFormat::Hdr10 / HdrFormat::DolbyVision
+//! ```
+//!
+//! # Architecture
+//!
+//! ```text
+//! DriveSession          — open, identify, unlock, read sectors
+//!   ├── ScsiTransport   — SG_IO (Linux), IOKit (macOS planned)
+//!   ├── DriveProfile    — per-drive unlock parameters (206 bundled)
+//!   ├── DriveId         — INQUIRY + GET_CONFIG 010C identification
+//!   └── Platform
+//!       └── Mt1959      — MediaTek unlock/read (Renesas planned)
+//!
+//! Disc                  — scan titles, streams, sector ranges
+//!   ├── UDF reader      — Blu-ray UDF 2.50 with metadata partitions
+//!   ├── MPLS parser     — playlists → titles + clips + STN streams
+//!   └── CLPI parser     — clip info → EP map → sector extents
+//! ```
+//!
+//! # Error Codes
+//!
+//! All errors are structured with numeric codes (E1000-E6000).
+//! No user-facing English text — applications format their own messages.
+//!
+//! | Range | Category |
+//! |-------|----------|
+//! | E1xxx | Device errors (not found, permission) |
+//! | E2xxx | Profile errors (unsupported drive, parse) |
+//! | E3xxx | Unlock errors (failed, signature mismatch) |
+//! | E4xxx | SCSI errors (command failed, timeout) |
+//! | E5xxx | I/O errors |
+//! | E6xxx | Disc format errors |
 
 pub mod error;
 pub mod scsi;