Merge pull request #240 from rust-osdev/doc2

multiboot2-common: improve README and diagrams

Author: phip1611

multiboot2-common/README.md

@@ -5,22 +5,33 @@
 
 Common helpers for the `multiboot2` and `multiboot2-header` crates.
 
-## Architecture
+## Architecture Diagrams
 
 The following figures, not displayable in `lib.rs` / on `docs.rs` unfortunately,
-outline the design of this crate:
-
-![Overview Multiboot2 Structures](./overview-multiboot2-structures.drawio.png "Overview Multiboot2 Structures")
-
-Overview of Multiboot2 structures: Multiboot2 boot information, boot
-information tags, Multiboot2 headers, and Multiboot2 header tags all share the
-same technical foundation: They have a common header and a possible dynamic
-size, depending on the header.
-
-![Crate Architecture Overview](./architecture.drawio.png "Crate Architecture Overview")
-
-Overview of how raw bytes are modelled to be representable by high-level
-ABI-compatible rusty types.
+outline the design of this crate. In the following figure, you can see the
+four classes of Multiboot2 structures and their memory properties. The four
+kinds of Multiboot2 structures are boot information, boot information
+tags, header, and header tags. All share the same technical foundation: They
+have a common header and a possible dynamic size, depending on the header.
+
+![Overview Multiboot2 structures](./overview-multiboot2-structures.drawio.png "Overview of Multiboot2 structures and their memory properties")
+
+In the next figure, you see how the types from `multiboot2-common` are used
+to parse a raw byte slice as the corresponding Multiboot2 structure a safe
+manner. The `BytesRef` wrapper ensures basic memory guarantees for the
+underlying `&[u8]` slice, while `DynSizedStructure` can then be used to
+safely cast to the target type.
+
+![Parsing flow overview](./parsing-flow.drawio.png "Parsing flow overview: From raw bytes to specific structures")
+
+The last complex figure shows all traits and structs from `multiboot2-common`,
+their internal relation, and how consumers (`multiboot2` and
+`multiboot2-header`) consume them. As this figure is quite complex, we recommend
+to first study the inner box (`multiboot2-common`) and then study how types from
+`multiboot2` (orange) and `multiboot2-header` (green) interface with
+`multiboot2-common`.
+
+![Architecture overview](./architecture.drawio.png "Architecture overview")
 
 ## MSRV
 

multiboot2-common/architecture.drawio.png

@@ -143,11 +143,14 @@
 //!
 //! # Architecture & Provided Abstractions
 //!
-//! Figure 2 in the [README](https://crates.io/crates/multiboot2-common)
+//! The figures in the [README](https://crates.io/crates/multiboot2-common)
 //! (currently not embeddable in lib.rs unfortunately) provides an overview of
 //! the parsing of Multiboot2 structures and how the definitions from this
 //! crate are used.
 //!
+//! Note that although the diagrams seem complex, most logic is in
+//! `multiboot2-common`. For downstream users, the usage is quite simple.
+//!
 //! ## Parsing and Casting
 //!
 //! First, we need byte slices which are guaranteed to be aligned and are a

multiboot2-common/architecture.drawio.xml

@@ -90,6 +90,8 @@ pub trait Tag: MaybeDynSized {
     const ID: Self::IDType;
 }
 
+// This implementation is not needed for parsing but for creation, when
+// downstream types just wrap this type.
 impl<H: Header> MaybeDynSized for DynSizedStructure<H> {
     type Header = H;