From cff6db259ad59c37f3935ee66fc47a21e72e3233 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Thu, 11 Apr 2024 12:42:19 +0200
Subject: [PATCH] doc: update fs documentation

---
 uefi/src/fs/file_system/fs.rs |  4 ++++
 uefi/src/fs/mod.rs            | 23 ++++++++++++++++++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/uefi/src/fs/file_system/fs.rs b/uefi/src/fs/file_system/fs.rs
index 2c15f1b21..2d57fc442 100644
--- a/uefi/src/fs/file_system/fs.rs
+++ b/uefi/src/fs/file_system/fs.rs
@@ -17,6 +17,10 @@ pub type FileSystemResult<T> = Result<T, Error>;
 /// High-level file-system abstraction for UEFI volumes with an API that is
 /// close to `std::fs`. It acts as convenient accessor around the
 /// [`SimpleFileSystemProtocol`].
+///
+/// Please refer to the [module documentation] for more information.
+///
+/// [module documentation]: uefi::fs
 pub struct FileSystem<'a>(ScopedProtocol<'a, SimpleFileSystemProtocol>);
 
 impl<'a> FileSystem<'a> {
diff --git a/uefi/src/fs/mod.rs b/uefi/src/fs/mod.rs
index aa2b2968d..d32ee483c 100644
--- a/uefi/src/fs/mod.rs
+++ b/uefi/src/fs/mod.rs
@@ -1,5 +1,5 @@
 //! A high-level file system API for UEFI applications close to the `std::fs`
-//! module from Rust's standard library. The main type by this module is
+//! module from Rust's standard library. The main export of this module is
 //! [`FileSystem`].
 //!
 //! # Difference to typical File System Abstractions
@@ -20,6 +20,25 @@
 //! files with plain linear paths to them. For more information, see
 //! [`Path`] and [`PathBuf`].
 //!
+//! ## Use `&str` as Path
+//! A `&str` known at compile time can be converted to a [`Path`] using the
+//! [`cstr16!`] macro. During runtime, you can create a path like this:
+//!
+//! ```no_run
+//! use uefi::CString16;
+//! use uefi::fs::{FileSystem, FileSystemResult};
+//! use uefi::prelude::BootServices;
+//! use uefi::proto::media::fs::SimpleFileSystem;
+//! use uefi::table::boot::ScopedProtocol;
+//!
+//! fn read_file(bs: BootServices, path: &str) -> FileSystemResult<Vec<u8>> {
+//!     let path: CString16 = CString16::try_from(path).unwrap();
+//!     let fs: ScopedProtocol<SimpleFileSystem> = bs.get_image_file_system(bs.image_handle()).unwrap();
+//!     let mut fs = FileSystem::new(fs);
+//!     fs.read(path.as_ref())
+//! }
+//! ```
+//!
 //! # API Hints
 //! There is no `File` abstraction as in the Rust `std` library. Instead, it is
 //! intended to work with the file system via dedicated functions, similar to
@@ -27,6 +46,8 @@
 //!
 //! There is no automatic synchronization of the file system for concurrent
 //! accesses. This is in the responsibility of the user.
+//!
+//! [`cstr16!`]: uefi_macros::cstr16
 
 mod dir_entry_iter;
 mod file_system;