From cdca03e91f7ab2bde082518d08548d4aca3b4a2e Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 10:23:54 +0200 Subject: [PATCH 1/2] doc: add "API/User Documentation, Documentation Structure, and other Resources" This is logically following the About section. --- uefi/README.md | 17 ----------------- uefi/src/lib.rs | 14 ++++++++++++++ 2 files changed, 14 insertions(+), 17 deletions(-) diff --git a/uefi/README.md b/uefi/README.md index 962fad270..69e168975 100644 --- a/uefi/README.md +++ b/uefi/README.md @@ -33,23 +33,6 @@ This crate's features are described in [`src/lib.rs`]. [`src/lib.rs`]: src/lib.rs -## User Documentation - - - -For a quick start, please check out [the UEFI application template](template). - -The [uefi-rs book] contains a tutorial, how-tos, and overviews of some important -UEFI concepts. Reference documentation for the various crates can be found on -[docs.rs]: - -- [docs.rs/uefi](https://docs.rs/uefi) -- [docs.rs/uefi-macros](https://docs.rs/uefi-macros) -- [docs.rs/uefi-raw](https://docs.rs/uefi-raw) - -[spec]: http://www.uefi.org/specifications -[uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD - ## MSRV The minimum supported Rust version is currently 1.70. diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 851dd74a7..66537afb8 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -69,6 +69,19 @@ //! The minimum supported Rust version is currently 1.70. //! Our policy is to support at least the past two stable releases. //! +//! # API/User Documentation, Documentation Structure, and other Resources +//! +//! Down below, you find typical technical documentation of all types, modules, +//! and functions exported by `uefi`. +//! +//! For a TL;DR quick start with an example on how to create your own EFI +//! application, please check out [the UEFI application template][template]. The +//! [Rust UEFI Book] is a more beginner-friendly tutorial with How-Tos, and +//! overviews of some important UEFI concepts and the abstractions provided by +//! this library. +//! +//! For more details of UEFI itself, see the latest [UEFI Specification][spec]. +//! //! # Crate organisation //! //! The top-level module contains some of the most used types and macros, @@ -190,6 +203,7 @@ //! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md //! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues //! [spec]: https://uefi.org/specifications +//! [template]: https://github.com/rust-osdev/uefi-rs/tree/main/template //! [unstable features]: https://doc.rust-lang.org/unstable-book/ //! [rustc-uefi-std]: https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html //! [uefi-std-tr-issue]: https://github.com/rust-lang/rust/issues/100499 From 63e37c4d4a2fd99b0ced55b793fd9175cd45803d Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 10:25:07 +0200 Subject: [PATCH 2/2] doc: lib.rs: Crate organization -> Library Structure & Tips Also added "UEFI Strings" subsection --- uefi/src/lib.rs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 66537afb8..e9a4e037b 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -82,13 +82,21 @@ //! //! For more details of UEFI itself, see the latest [UEFI Specification][spec]. //! -//! # Crate organisation +//! # Library Structure & Tips //! //! The top-level module contains some of the most used types and macros, //! including the [`Handle`] and [`Result`] types, the [`CStr16`] and //! [`CString16`] types for working with UCS-2 strings, and the [`entry`] and //! [`guid`] macros. //! +//! ## UEFI Strings +//! +//! Rust string literals are UTF-8 encoded and thus, not compatible with most +//! UEFI interfaces. We provide [`CStr16`] and [`CString16`] for proper working +//! with UCS-2 strings, including various transformation functions from standard +//! Rust strings. You can use [`ctr16!`] to create UCS-2 string literals at +//! compile time. +//! //! ## Tables //! //! The [`SystemTable`] provides access to almost everything in UEFI. It comes @@ -199,6 +207,7 @@ //! [`SystemTable`]: table::SystemTable //! [`r-efi`]: https://crates.io/crates/r-efi //! [`entry-macro`]: uefi_macros::entry +//! [`ctr16!`]: crate::cstr16 //! [`unsafe_protocol`]: proto::unsafe_protocol //! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md //! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues