Merge pull request #1291 from phip1611/doc4

doc: add comprehensive About section to lib.rs [doc: 3/N]

Author: nicholasbishop

uefi/README.md

@@ -11,6 +11,17 @@ This crate makes it easy to develop Rust software that leverages **safe**,
 ![Build status](https://github.com/rust-osdev/uefi-rs/workflows/Rust/badge.svg)
 ![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)
 
+## Value-add and Use Cases
+
+`uefi` supports writing code for both pre- and post-exit boot services
+epochs, but its true strength shines when you create UEFI images that heavily
+interact with UEFI boot services. Still, you have the flexibility to just
+integrate selected types and abstractions into your project, for example to
+parse the UEFI memory map.
+
+_Note that for producing UEFI images, you also need to use a corresponding
+`uefi` compiler target of Rust, such as `x86_64-unknown-uefi`._
+
 For an introduction to the `uefi-rs` project and documentation, please refer to
 our main [README].
 

uefi/src/lib.rs

@@ -7,18 +7,47 @@
 //! important UEFI concepts. For more details of UEFI, see the latest [UEFI
 //! Specification][spec].
 //!
-//! # Interaction with uefi services
+//! # Value-add and Use Cases
 //!
-//! With this crate you can write code for the pre- and post-exit boot services
-//! epochs. However, the `uefi` crate unfolds its true potential when
-//! interacting with UEFI boot services.
+//! `uefi` supports writing code for both pre- and post-exit boot services
+//! epochs, but its true strength shines when you create UEFI images that heavily
+//! interact with UEFI boot services. Still, you have the flexibility to just
+//! integrate selected types and abstractions into your project, for example to
+//! parse the UEFI memory map.
 //!
-//! ## Supported Architectures
+//! _Note that for producing UEFI images, you also need to use a corresponding
+//! `uefi` compiler target of Rust, such as `x86_64-unknown-uefi`._
+//!
+//! ## Example Use Cases
+//!
+//! This library significantly simplifies the process of creating **UEFI images**
+//! by abstracting away much of the UEFI API complexity and by providing
+//! convenient wrappers. When we mention UEFI images, we are talking about UEFI
+//! applications, UEFI boot service drivers, and EFI runtime service drivers,
+//! which typically have the `.efi` file extension. For instance, an UEFI
+//! application could be an OS-specific loader, similar to _GRUB_ or _Limine_.
+//!
+//! Additionally, you can use this crate in non-UEFI images (such as a kernel
+//! in ELF format) to perform tasks like parsing the UEFI memory map embedded in
+//! the boot information provided by a bootloader. It also enables access to
+//! UEFI runtime services from a non-UEFI image kernel.
+//!
+//! # Supported Compiler Versions and Architectures
+//!
+//! `uefi` works with stable Rust, but additional nightly-only features are
+//! gated behind the `unstable` Cargo feature. Please find more information
+//! about additional crate features below.
 //!
 //! `uefi` is compatible with all platforms that both the Rust compiler and
 //! UEFI support, such as `i686`, `x86_64`, and `aarch64`. Please note that we
 //! can't test all possible hardware/firmware/platform combinations in CI.
 //!
+//! ## MSRV
+//! <!-- Keep in Sync with README! -->
+//!
+//! The minimum supported Rust version is currently 1.70.
+//! Our policy is to support at least the past two stable releases.
+//!
 //! # Crate organisation
 //!
 //! The top-level module contains some of the most used types and macros,
@@ -86,12 +115,6 @@
 //! Contributions in the form of a PR are also highly welcome. Check our
 //! [contributing guide][contributing] for details.
 //!
-//! # MSRV
-//! <!-- Keep in Sync with README! -->
-//!
-//! The minimum supported Rust version is currently 1.70.
-//! Our policy is to support at least the past two stable releases.
-//!
 //! # License
 //! <!-- Keep in Sync with README! -->
 //!
@@ -101,6 +124,11 @@
 //!
 //! The full text of the license is available in the [license file][LICENSE].
 //!
+//! # Terminology
+//!
+//! Both "EFI" and "UEFI" can be used interchangeably, such as "UEFI image" or
+//! "EFI image". We prefer "UEFI" in our crate and its documentation.
+//!
 //! [LICENSE]: https://github.com/rust-osdev/uefi-rs/blob/main/uefi/LICENSE
 //! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/
 //! [UEFI]: https://uefi.org/