Write some docs

Author: Cryptjar

README.md

@@ -20,13 +20,13 @@ compiler.
 ## MSRV
 
 This crate only works with a Rust `nightly-2021-01-07` compiler, which is,
-as of the time of writing (early 2022), still the latest version that
+as of the time of writing (early 2022), still the most recent version that
 supports AVR
 (see <https://github.com/rust-lang/compiler-builtins/issues/400>).
 So it is actually, the minimum and maximum supported version.
 All versions `0.2.x` will adhere to work with `nightly-2021-01-07`.
 
-Future versions such as `0.3.x` might required a new different Rust compiler
+Future versions such as `0.3.x` might required a newer Rust compiler
 version.
 
 
@@ -76,7 +76,7 @@ data memory, causing **undefined behavior**!
 ## Example
 
 ```rust
-use avr_progmem::read_byte;
+use avr_progmem::raw::read_byte;
 
 // This `static` must never be directly dereferenced/accessed!
 // So a `let data: u8 = P_BYTE;` is **undefined behavior**!!!
@@ -136,6 +136,28 @@ assert_eq!(b'A', data);
 ```
 
 
+# Strings
+
+Using strings such as `&str` with [`ProgMem`] is rather difficult, and
+surprisingly hard if Unicode support is needed
+(see <https://github.com/Cryptjar/avr-progmem-rs/issues/3>).
+Thus, to make working with string convenient the
+[`PmString`](string::PmString) struct is provided on top of [`ProgMem`].
+
+[`PmString`](string::PmString) stores any given `&str` as statically sized
+UTF-8 byte array (with full Unicode support).
+To make its content usable, it provides a `Display` & `uDisplay`
+implementation, a lazy `char` iterator, and `load` function similar to
+[`ProgMem`], that yields a [`LoadedString`](string::LoadedString),
+which in turn defers to `&str`.
+
+TODO: how about the in-line macro
+
+## Example
+
+TODO
+
+
 # Other Architectures
 
 As mentioned before, this crate is specifically designed to be use with

src/lib.rs

@@ -27,13 +27,13 @@
 //! ## MSRV
 //!
 //! This crate only works with a Rust `nightly-2021-01-07` compiler, which is,
-//! as of the time of writing (early 2022), still the latest version that
+//! as of the time of writing (early 2022), still the most recent version that
 //! supports AVR
 //! (see <https://github.com/rust-lang/compiler-builtins/issues/400>).
 //! So it is actually, the minimum and maximum supported version.
 //! All versions `0.2.x` will adhere to work with `nightly-2021-01-07`.
 //!
-//! Future versions such as `0.3.x` might required a new different Rust compiler
+//! Future versions such as `0.3.x` might required a newer Rust compiler
 //! version.
 //!
 //!
@@ -143,6 +143,28 @@
 //! ```
 //!
 //!
+//! # Strings
+//!
+//! Using strings such as `&str` with [`ProgMem`] is rather difficult, and
+//! surprisingly hard if Unicode support is needed
+//! (see <https://github.com/Cryptjar/avr-progmem-rs/issues/3>).
+//! Thus, to make working with string convenient the
+//! [`PmString`](string::PmString) struct is provided on top of [`ProgMem`].
+//!
+//! [`PmString`](string::PmString) stores any given `&str` as statically sized
+//! UTF-8 byte array (with full Unicode support).
+//! To make its content usable, it provides a `Display` & `uDisplay`
+//! implementation, a lazy `char` iterator, and `load` function similar to
+//! [`ProgMem`], that yields a [`LoadedString`](string::LoadedString),
+//! which in turn defers to `&str`.
+//!
+//! TODO: how about the in-line macro
+//!
+//! ## Example
+//!
+//! TODO
+//!
+//!
 //! # Other Architectures
 //!
 //! As mentioned before, this crate is specifically designed to be use with
@@ -194,6 +216,6 @@
 
 pub mod raw;
 pub mod string;
-mod wrapper;
+pub mod wrapper;
 
 pub use wrapper::ProgMem;

src/raw.rs

@@ -1,3 +1,21 @@
+//! Raw direct progmem access
+//!
+//! This module provides functions to directly access the progmem, such as
+//! [read_value].
+//!
+//! It is recommended to use best-effort wrappers in [wrapper](crate::wrapper)
+//! and [string](crate::string), which use these functions internally.
+//! This is in particular, because having a raw `static` that is stored in the
+//! progmem is very hazardous since Rust does not understand the difference
+//! between the normal data memory domain and the program memory domain, and
+//! allows safe code to directly access those raw progmem statics, which is
+//! **undefined behavior**.
+//! The wrapper types in [wrapper](crate::wrapper) and [string](crate::string),
+//! prevent safe code from directly accessing these statics and only offer
+//! dedicated accessor methods that first load the data into the normal data
+//! memory domain via the function of this module.
+
+
 use core::mem::size_of;
 use core::mem::MaybeUninit;
 

src/string.rs

@@ -1,3 +1,36 @@
+//! String utilities
+//!
+//! This module offers further utilities base on [`ProgMem`] to make working
+//! with strings in progmem more convenient.
+//!
+//! The difficulty with strings is that normally they are either heap allocated
+//! (as with the std Rust `String`) or dynamically sized (as with `str`).
+//! To store a string in progmem, one needs first of all a fixed-sized storage
+//! variant of a `str`.
+//! One option is to use byte string literals (e.g. `b"foobar"`), however,
+//! for some reason those only accept ASCII and no Unicode.
+//! At some day, one might be able to to convert arbitrary string literals to
+//! byte arrays like this:
+//!
+//! ```ignore
+//! # use std::convert::TryInto;
+//! // Dose not compile as of 1.51, because `try_into` is not a const fn
+//! static WIKIPEDIA: [u8; 12] = "维基百科".as_bytes().try_into().unwrap();
+//! ```
+//!
+//! As a convenient workaround, this module offers:
+//! * [`LoadedString`] a simple UTF-8 encoded sized byte array
+//! * [`PmString`] a UTF-8 encoded sized byte array in progmem similar to [`ProgMem`].
+//!
+//! Also the [`progmem`](crate::progmem) macro offers a special syntax for
+//! converting a normal string literal into a [`PmString`]:
+//!
+//! ```rust
+//! // TODO: code
+//! ```
+//!
+
+
 use core::convert::TryFrom;
 use core::fmt;
 use core::ops::Deref;
@@ -175,10 +208,19 @@ impl<const N: usize> ufmt::uDisplay for LoadedString<N> {
 /// A byte string in progmem
 ///
 /// Not to be confused with a [`LoadedString`].
-/// A `LoadedString` is just a wrapper around a byte array (`[u8;N]`) that can
-/// be put into a [`ProgMem`].
-/// A `PmString` on the other hand, is a wrapper around a
-/// `ProgMem<[u8;N]>`.
+/// A `LoadedString` is a simple wrapper around a byte array (`[u8;N]`) that
+/// derefs to `str`, and should be used in RAM.
+/// A `PmString` on the other hand, is a wrapper around a byte array in progmem
+/// aka around a `ProgMem<[u8;N]>`, and thus must always be progmem.
+/// Similar to `ProgMem`, `PmString` offers a [`load`](PmString::load) method to
+/// load its entire content into RAM.
+/// The loaded content will be a `LoadedString`, hence the name.
+///
+/// Besides loading the entire string at once into RAM, `PmString` also offers
+/// a lazy [`chars`](PmString::chars) iterator method, that will load just one
+/// char at a time.
+/// This allows `chars` to be used on very large strings that do not fit into
+/// the RAM as whole.
 ///
 /// # Safety
 ///
@@ -208,6 +250,8 @@ impl<const N: usize> PmString<N> {
 	/// This function is only sound to call, if the value is
 	/// stored in a static that is for instance attributed with
 	/// `#[link_section = ".progmem.data"]`.
+	///
+	/// You are encouraged to use the [`progmem`] macro instead.
 	pub const unsafe fn new(s: &str) -> Option<Self> {
 		Self::from_bytes(s.as_bytes())
 	}
@@ -267,6 +311,18 @@ impl<const N: usize> PmString<N> {
 	}
 
 	/// Loads the entire string into RAM
+	///
+	/// # Panics
+	///
+	/// This method panics, if the size of the value (i.e. `N`) is beyond 255
+	/// bytes.
+	/// However, this is currently just a implementation limitation, which may
+	/// be lifted in the future.
+	///
+	/// If you have a very large string, consider using the lazy
+	/// [`chars`](Self::chars) iterator that accesses the string by one char at
+	/// a time and thus does not have such a limitation.
+	///
 	pub fn load(&self) -> LoadedString<N> {
 		let array = self.load_bytes();
 
@@ -279,6 +335,17 @@ impl<const N: usize> PmString<N> {
 	}
 
 	/// Loads the entire string as byte array into RAM
+	///
+	/// # Panics
+	///
+	/// This method panics, if the size of the value (i.e. `[u8; N]`) is beyond
+	/// 255 bytes.
+	/// However, this is currently just a implementation limitation, which may
+	/// be lifted in the future.
+	///
+	/// If you have a very large string, consider using the lazy
+	/// [`chars`](Self::chars) iterator or the respective byte iterator
+	/// (via `as_bytes().iter()`).
 	pub fn load_bytes(&self) -> [u8; N] {
 		self.as_bytes().load()
 	}
@@ -290,8 +357,9 @@ impl<const N: usize> PmString<N> {
 
 	/// Lazily iterate over the `char`s of the string.
 	///
-	/// This function is analog to [`ProgMem::iter`], except it is over the
-	/// `char`s of this string.
+	/// This function is analog to [`ProgMem::iter`], except it performs UTF-8
+	/// parsing and returns the `char`s of this string, thus it is more similar
+	/// to [`str::chars`].
 	pub fn chars(&self) -> PmChars<N> {
 		PmChars::new(self)
 	}

src/wrapper.rs

@@ -1,3 +1,22 @@
+//! Best-effort safe wrapper for progmem.
+//!
+//! This module offers the [`ProgMem`] struct that wraps a value in progmem,
+//! and only gives access to this value via methods that first load the value
+//! into the normal data memory domain.
+//! This is also the reason why the value must be `Copy` and is always returned
+//! by-value instead of by-reference (since the value is not in the data memory
+//! where it could be referenced).
+//!
+//! Since the `ProgMem` struct loads the value using special instructions,
+//! it must actually be in progmem, otherwise it would be
+//! **undefined behavior**, therefore, its constructor is `unsafe` where the
+//! caller must guarantee that it is indeed stored in progmem.
+//!
+//! As further convenience, the [`progmem`] macro is offered that will create
+//! a `static` in progmem and wrap the given value in the [`ProgMem`] struct
+//! for you.
+
+
 use core::convert::TryInto;
 
 use crate::raw::read_value;
@@ -142,6 +161,9 @@ impl<T: Copy, const N: usize> ProgMem<[T; N]> {
 	/// However, this is currently just a implementation limitation, which may
 	/// be lifted in the future.
 	///
+	/// Notice, that here `T` is the type of the elements not the entire array
+	/// as it would be with [`load`](Self::load).
+	///
 	pub fn load_at(&self, idx: usize) -> T {
 		// Just take a reference to the selected element.
 		// Notice that this will execute a bounds check.
@@ -213,6 +235,9 @@ impl<T: Copy, const N: usize> ProgMem<[T; N]> {
 	/// However, this is currently just a implementation limitation, which may
 	/// be lifted in the future.
 	///
+	/// Notice, that here `T` is the type of the elements not the entire array
+	/// as it would be with [`load`](Self::load).
+	///
 	pub fn iter(&self) -> PmIter<T, N> {
 		PmIter::new(self)
 	}