Improve API docs, add docs.rs badge + link

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.
 

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
+//! Drive access, disc format parsing, and raw sector reading in one library.
-//! Blu-ray drives, allowing direct sector access for disc archival
+//! 206 bundled drive profiles. No external files, no configuration.
-//! and backup purposes.
 //!
-//! # Architecture
+//! # Drive Access
-//!
-//! 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
 //!
 //! ```no_run
 //! use libfreemkv::DriveSession;
 //! use std::path::Path;
 //!
-//! let mut session = DriveSession::open(
+//! // Open drive — profiles are bundled, auto-identify
-//!     Path::new("/dev/sr0"),
+//! let mut session = DriveSession::open(Path::new("/dev/sr0")).unwrap();
-//! ).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;