From bae3c694bd377f7a031d0598ef5880f5ea08ba13 Mon Sep 17 00:00:00 2001
From: Dzmitry Malyshau <kvarkus@gmail.com>
Date: Sat, 5 Jun 2021 02:01:12 -0400
Subject: [PATCH] Documentation update

---
 README.md            | 3 ++-
 wgpu-core/src/lib.rs | 5 +++++
 wgpu-hal/src/lib.rs  | 8 ++++++++
 3 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6f5b2c6b9d..713e653d40 100644
--- a/README.md
+++ b/README.md
@@ -7,12 +7,13 @@
 [![codecov.io](https://codecov.io/gh/gfx-rs/wgpu/branch/master/graph/badge.svg?token=84qJTesmeS)](https://codecov.io/gh/gfx-rs/wgpu)
 
 This is an implementation of [WebGPU](https://www.w3.org/community/gpu/) API in Rust, targeting both native and the Web.
-It's written in Rust and is based on [gfx-hal](https://github.com/gfx-rs/gfx) with help of [gpu-alloc](https://github.com/zakarumych/gpu-alloc) and [gpu-descriptor](https://github.com/zakarumych/gpu-descriptor). See the upstream [WebGPU specification](https://gpuweb.github.io/gpuweb/) (work in progress).
+See the upstream [WebGPU specification](https://gpuweb.github.io/gpuweb/) (work in progress).
 
 The repository hosts the following parts:
 
   - [![Crates.io](https://img.shields.io/crates/v/wgpu.svg?label=wgpu)](https://crates.io/crates/wgpu) [![docs.rs](https://docs.rs/wgpu/badge.svg)](https://docs.rs/wgpu/) - public Rust API for users
   - [![Crates.io](https://img.shields.io/crates/v/wgpu-core.svg?label=wgpu-core)](https://crates.io/crates/wgpu-core) [![docs.rs](https://docs.rs/wgpu-core/badge.svg)](https://docs.rs/wgpu-core/) - internal Rust API for WebGPU implementations to use
+  - [![Crates.io](https://img.shields.io/crates/v/wgpu-hal.svg?label=wgpu-hal)](https://crates.io/crates/wgpu-hal) [![docs.rs](https://docs.rs/wgpu-hal/badge.svg)](https://docs.rs/wgpu-hal/) - internal unsafe GPU abstraction API
   - [![Crates.io](https://img.shields.io/crates/v/wgpu-types.svg?label=wgpu-types)](https://crates.io/crates/wgpu-types) [![docs.rs](https://docs.rs/wgpu-types/badge.svg)](https://docs.rs/wgpu-types/) - Rust types shared between `wgpu-core` and `wgpu-rs`
   - `player` - standalone application for replaying the API traces, uses `winit`
 
diff --git a/wgpu-core/src/lib.rs b/wgpu-core/src/lib.rs
index ea3b9b84db..5f2c886c1b 100644
--- a/wgpu-core/src/lib.rs
+++ b/wgpu-core/src/lib.rs
@@ -2,6 +2,11 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
+/*! This library safely implements WebGPU on native platforms.
+ *  It is designed for integration into browsers, as well as wrapping
+ *  into other language-specific user-friendly libraries.
+ */
+
 #![allow(
     // We use loops for getting early-out of scope without closures.
     clippy::never_loop,
diff --git a/wgpu-hal/src/lib.rs b/wgpu-hal/src/lib.rs
index 9124192aad..b777645985 100644
--- a/wgpu-hal/src/lib.rs
+++ b/wgpu-hal/src/lib.rs
@@ -3,6 +3,14 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 /*! This library describes the internal unsafe graphics abstraction API.
+ *  It follows WebGPU for the most part, re-using wgpu-types,
+ *  with the following deviations:
+ *  - Fully unsafe: zero overhead, zero validation.
+ *  - Compile-time backend selection via traits.
+ *  - Objects are passed by references and returned by value. No IDs.
+ *  - Mapping is persistent, with explicit synchronization.
+ *  - Resource transitions are explicit.
+ *  - All layouts are explicit.
  */
 
 #![allow(