docs: complete crates.io API documentation

Author: Chlna6666

.github/workflows/publish.yml

@@ -55,9 +55,13 @@ jobs:
         run: cargo test --no-default-features
       - name: Docs
         run: cargo doc --all-features --no-deps
+      - name: Public API docs
+        run: cargo rustdoc --all-features -- -D missing_docs
       - name: Dry run
         run: cargo publish --dry-run
-      - name: Publish
-        env:
-          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
-        run: cargo publish --no-verify
+      # Publishing is intentionally disabled until the release owner configures
+      # crates.io publishing outside this repository.
+      # - name: Publish
+      #   env:
+      #     CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+      #   run: cargo publish --no-verify

CHANGELOG.md

@@ -6,6 +6,11 @@ All notable changes to `bedrock-world` are tracked here.
 
 ### Changed
 
+- Added docs.rs all-features metadata, crate-level feature guidance, and
+  README sections describing hosted docs, feature behavior, and package
+  contents.
+- Added complete public API rustdoc coverage and enabled the release workflow's
+  missing-docs gate for all-feature rustdoc builds.
 - Prepared the crate for publishing by removing `publish = false` and declaring
   the optional `bedrock-leveldb` backend as a versioned `0.2.1` dependency while
   retaining the local `../bedrock-leveldb` path for repository development.

Cargo.toml

@@ -30,6 +30,9 @@ include = [
 name = "bedrock_world"
 path = "src/bedrock_world.rs"
 
+[package.metadata.docs.rs]
+all-features = true
+
 [features]
 default = ["async", "backend-bedrock-leveldb"]
 async = ["dep:tokio"]

README.md

@@ -31,18 +31,32 @@ This crate focuses on complete parsing behavior. The
   `db/CURRENT` worlds as LevelDB, marks early `StorageVersion <= 4` worlds as
   `WorldFormat::LevelDbLegacyTerrain`, and opens pre-LevelDB `chunks.dat` worlds
   as `WorldFormat::PocketChunksDat`.
+- `OpenOptions::default()` is read-only. Any world-record write must reopen the
+  world with `OpenOptions { read_only: false, ..OpenOptions::default() }`.
+  Read-only worlds return `BedrockWorldErrorKind::ReadOnly` from high-level
+  writes before touching storage.
 - Use category APIs for UI and tools:
   `classify_keys_blocking`, `list_players_blocking`,
   `list_chunk_positions_blocking`, `parse_chunk_blocking`,
   `parse_subchunk_blocking`, `scan_entities_blocking`,
   `scan_block_entities_blocking`, `scan_items_blocking`, `scan_maps_blocking`,
   `scan_villages_blocking`, and `scan_globals_blocking`.
-- Use typed v0.2 edit APIs for BedrockLevelFormat records:
-  `read_map_record_blocking`, `scan_map_records_blocking`,
-  `write_map_record_blocking`, `read_global_record_blocking`,
-  `scan_global_records_blocking`, `put_hsa_for_chunk_blocking`,
-  `block_entities_in_chunk_blocking`, `edit_block_entity_at_blocking`,
-  `actors_in_chunk_blocking`, and `put_actor_blocking`.
+- Use typed v0.2 BedrockLevelFormat write APIs on a writable world:
+  `write_map_record_blocking`, `delete_map_record_blocking`,
+  `write_global_record_blocking`, `delete_global_record_blocking`,
+  `put_heightmap_blocking`, `put_biome_storage_blocking`,
+  `put_hsa_for_chunk_blocking`, `delete_hsa_for_chunk_blocking`,
+  `put_block_entities_blocking`, `edit_block_entity_at_blocking`,
+  `delete_block_entity_at_blocking`, `put_actor_blocking`,
+  `delete_actor_blocking`, and `move_actor_blocking`. Matching async wrappers
+  are available behind the default `async` feature.
+- High-level writes serialize and parse records back before commit. Actor writes
+  update `digp -> actorprefix` records in one transaction. Block-entity writes
+  validate coordinates against the target chunk. `PocketChunksDatStorage`
+  remains read-only.
+- `bedrock-world` stops at Bedrock key/value semantics. Post-write refresh,
+  invalidation, and presentation policy belong to downstream applications or
+  adapter crates.
 - Async wrappers use `tokio::task::spawn_blocking`, so disk and decode work does
   not block the foreground async runtime.
 - `WorldScanOptions` controls threading, cancellation, and progress callbacks.
@@ -275,6 +289,22 @@ Latest local Criterion and large-fixture results are tracked in
 is intentionally separate from Criterion because multi-million-entry scans
 should not be repeated inside microbenchmarks.
 
+## Features And docs.rs
+
+docs.rs builds with all features enabled, so the hosted API reference includes
+async wrappers and the optional `bedrock-leveldb` backend.
+
+| Feature | Default | Meaning |
+| --- | --- | --- |
+| `async` | yes | Adds async wrappers that delegate blocking filesystem, LevelDB, and NBT work to `tokio::task::spawn_blocking` |
+| `backend-bedrock-leveldb` | yes | Enables opening native Bedrock LevelDB worlds through `bedrock-leveldb` |
+| `leveldb-mmap` | no | Enables the backend and forwards the `bedrock-leveldb/mmap` feature |
+
+Disable default features when a tool only needs pure parsing, in-memory storage,
+`level.dat`, or NBT helpers. The crates.io package includes the English and
+Chinese READMEs, guide documents under `docs/`, the changelog, licenses,
+source, tests, fixture documentation, and benchmarks.
+
 ## Completeness
 
 | Area | Status |

README.zh-CN.md

@@ -19,18 +19,29 @@ terrain record 的 chunk/subchunk 解析、实体和方块实体解析、物品
   时打开 LevelDB，`StorageVersion <= 4` 的早期世界会标记为
   `WorldFormat::LevelDbLegacyTerrain`；只有 `chunks.dat` 时打开
   `WorldFormat::PocketChunksDat`。
+- `OpenOptions::default()` 是只读模式。任何世界记录写入都必须用
+  `OpenOptions { read_only: false, ..OpenOptions::default() }` 重新打开
+  world。只读 world 的高层写入会在访问 storage 前返回
+  `BedrockWorldErrorKind::ReadOnly`。
 - UI 和工具应优先使用分类 API：
   `classify_keys_blocking`、`list_players_blocking`、
   `list_chunk_positions_blocking`、`parse_chunk_blocking`、
   `parse_subchunk_blocking`、`scan_entities_blocking`、
   `scan_block_entities_blocking`、`scan_items_blocking`、`scan_maps_blocking`、
   `scan_villages_blocking`、`scan_globals_blocking`。
-- BedrockLevelFormat 记录编辑使用 v0.2 typed API：
-  `read_map_record_blocking`、`scan_map_records_blocking`、
-  `write_map_record_blocking`、`read_global_record_blocking`、
-  `scan_global_records_blocking`、`put_hsa_for_chunk_blocking`、
-  `block_entities_in_chunk_blocking`、`edit_block_entity_at_blocking`、
-  `actors_in_chunk_blocking`、`put_actor_blocking`。
+- BedrockLevelFormat 记录写入使用 v0.2 typed API，并且必须在可写 world 上执行：
+  `write_map_record_blocking`、`delete_map_record_blocking`、
+  `write_global_record_blocking`、`delete_global_record_blocking`、
+  `put_heightmap_blocking`、`put_biome_storage_blocking`、
+  `put_hsa_for_chunk_blocking`、`delete_hsa_for_chunk_blocking`、
+  `put_block_entities_blocking`、`edit_block_entity_at_blocking`、
+  `delete_block_entity_at_blocking`、`put_actor_blocking`、
+  `delete_actor_blocking`、`move_actor_blocking`。默认 `async` feature 下有同名 async wrapper。
+- 高层写入会先 serialize，再 parse 回来校验，然后才提交。actor 写入在一个 transaction
+  中同步维护 `digp -> actorprefix`；方块实体写入会校验坐标仍属于目标 chunk。
+  `PocketChunksDatStorage` 继续只读。
+- `bedrock-world` 只负责 Bedrock key/value 语义。写入后的刷新、失效和展示策略属于
+  下游应用或适配 crate。
 - async wrapper 使用 `tokio::task::spawn_blocking`，磁盘 I/O 和解析不会阻塞前台 async runtime。
 - `WorldScanOptions` 控制线程、取消和进度回调。
 - `WorldPipelineOptions` 进一步控制有界 pipeline 的队列深度、chunk batch 大小、
@@ -229,6 +240,21 @@ players.count=290
 [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md)。大型 fixture harness 与 Criterion
 分离，因为多百万 entry 扫描不应该在 microbenchmark 中反复运行。
 
+## Features 和 docs.rs
+
+docs.rs 会启用全部 features 构建，因此托管 API 文档会包含 async wrapper 和可选的
+`bedrock-leveldb` 后端。
+
+| Feature | 默认 | 含义 |
+| --- | --- | --- |
+| `async` | 是 | 添加 async wrapper，并把阻塞的文件系统、LevelDB 和 NBT 工作交给 `tokio::task::spawn_blocking` |
+| `backend-bedrock-leveldb` | 是 | 通过 `bedrock-leveldb` 打开原生 Bedrock LevelDB 世界 |
+| `leveldb-mmap` | 否 | 启用后端并转发 `bedrock-leveldb/mmap` feature |
+
+只需要纯解析、内存 storage、`level.dat` 或 NBT helper 的工具可以关闭默认 features。
+crates.io 包包含英文/中文 README、`docs/` 下的指南、changelog、许可证、源码、
+测试、fixture 文档和 benchmark。
+
 ## 完整度
 
 | 范围 | 状态 |

docs/API.md

@@ -22,9 +22,11 @@ bytes by parsing them back before replacing the file.
 
 `BedrockWorld::open(path, OpenOptions::default())` opens a world in read-only
 mode and auto-detects `db/CURRENT` LevelDB worlds or old Pocket Edition
-`chunks.dat` worlds. `BedrockWorld::open_blocking` exposes the same detection
-for CLI tools and examples. Use targeted APIs instead of full-world parsing for
-UI flows:
+`chunks.dat` worlds. Open with `OpenOptions { read_only: false, ..Default::default() }`
+only for explicit edit flows; high-level writes call `ensure_writable` and
+return `BedrockWorldErrorKind::ReadOnly` on read-only handles before any storage
+mutation. `BedrockWorld::open_blocking` exposes the same detection for CLI tools
+and examples. Use targeted APIs instead of full-world parsing for UI flows:
 
 - `list_players_blocking`
 - `classify_keys_blocking`
@@ -154,7 +156,10 @@ old 82,176-byte `chunks.dat` terrain payload to an 83,200-byte virtual
 v0.2 adds typed APIs for BedrockLevelFormat records that map editors usually
 need without forcing a full-world parse. The storage boundary remains raw
 key/value: `bedrock-world` owns Bedrock key classification, NBT codecs,
-coordinate validation, and write roundtrip checks.
+coordinate validation, and write roundtrip checks. This crate does not decide
+how callers refresh or invalidate their presentation state after a write;
+downstream applications and adapter crates map these semantic writes to their
+own update model.
 
 Key helpers:
 
@@ -195,7 +200,17 @@ Chunk payload helpers:
 All high-level writes validate the serialized value by parsing it back before
 committing. Actor writes update `actorprefix` and `digp` in one transaction.
 Block-entity writes reject coordinates outside the target chunk. `chunks.dat`
-backends stay read-only.
+backends stay read-only. Write examples should therefore open a writable world:
+
+```rust
+let world = bedrock_world::BedrockWorld::open_blocking(
+    "world",
+    bedrock_world::OpenOptions {
+        read_only: false,
+        ..bedrock_world::OpenOptions::default()
+    },
+)?;
+```
 
 ## Parsing Modes
 

docs/TESTING.md

@@ -43,6 +43,20 @@ block, overlay/water context when present, and
 `RenderLoadStats::raw_height_mismatch_columns` is non-zero. Raw heightmap
 behavior belongs in `RenderChunkRequest::RawHeightMap` tests.
 
+Typed write tests should cover the storage-layer contract only:
+
+- `OpenOptions::default()` remains read-only and every high-level write returns
+  `BedrockWorldErrorKind::ReadOnly` before mutating storage.
+- Writable worlds are opened with
+  `OpenOptions { read_only: false, ..OpenOptions::default() }`.
+- map/global/HSA/heightmap/biome/block-entity writes serialize, parse back, and
+  read back with semantic equivalence.
+- actor writes update `digp -> actorprefix` records in one transaction.
+- `PocketChunksDatStorage` rejects `put`, `delete`, and batch writes.
+
+Do not add presentation-layer invalidation assertions here. Post-write refresh
+and scheduling behavior is a downstream responsibility.
+
 ## Benchmarks
 
 Run the v0.2 benchmark set with:

src/bedrock_world.rs

@@ -11,7 +11,15 @@
 //! [`BedrockWorld::parse_chunk_blocking`], or [`BedrockWorld::scan_items_blocking`].
 //! Async wrappers use `tokio::task::spawn_blocking` so `LevelDB` and NBT work does
 //! not run on foreground async tasks.
+//!
+//! # Features
+//!
+//! docs.rs builds this crate with all features enabled. Default builds enable
+//! `async` and the `bedrock-leveldb` backend. Disable default features for
+//! pure parsing, in-memory storage, `level.dat`, and NBT workflows that should
+//! not depend on a database backend.
 
+#![deny(missing_docs)]
 #![allow(
     clippy::cast_possible_truncation,
     clippy::cast_possible_wrap,