doc: improve lib.rs

Author: phip1611

uefi/src/lib.rs

@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
+//! # `uefi-rs`
+//!
 //! Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI].
 //!
 //! This crate makes it easy to develop Rust software that leverages **safe**,
@@ -208,10 +210,31 @@
 //! Licensed under either of [Apache License, Version 2.0][apache] or
 //! [MIT license][mit] at your option.
 //!
-//! # 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.
+//! # UEFI and `uefi-rs` Terminology
+//!
+//! Please look into the [specification][spec] for a comprehensive overview. In
+//! UEFI, both "EFI" and "UEFI" are often used interchangeably, such as
+//! "UEFI image" or "EFI image". We prefer "UEFI" in our crate and its
+//! documentation.
+//!
+//! ## Important UEFI Terms and Abstractions
+//!
+//! - **agent**: The entity (usually a driver or application) performing
+//!   operations on a handle or protocol.
+//! - **controller**: A handle that represents a hardware device managed by
+//!   drivers.
+//! - **device path**: A structured description of a device's location or
+//!   access method, used for booting and device identification.
+//! - **driver binding**: A service that matches drivers to controllers and
+//!   manages their lifecycle.
+//! - **image**: A loaded executable (e.g., UEFI application or driver) with its
+//!   own execution context - an `.efi` file (PE/COFF executable).
+//! - **handle**: An opaque identifier representing a UEFI object to which
+//!   protocols can be attached.
+//! - **protocol**: A standardized set of functions and data structures defining
+//!   an interface for services.
+//! - **(protocol) interface**: A concrete implementation of a protocol attached
+//!   to a handle.
 //!
 //! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/
 //! [UEFI]: https://uefi.org/