Add a callable memory layout validator, and clean up docs.

Author: bodil

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project
 adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### ADDED
+
+-   You can (and should) now call `smartstring::validate()` from your own code or test suite to
+    validate `SmartString`'s memory layout assumptions.
+
 ## [0.2.8] - 2021-07-26
 
 ### CHANGED

src/config.rs

@@ -7,47 +7,38 @@ use alloc::string::String;
 use core::mem::{align_of, size_of};
 use static_assertions::{assert_cfg, assert_eq_size, const_assert, const_assert_eq};
 
-/// A compact string representation equal to [`String`][String] in size with guaranteed inlining.
+/// A compact string representation equal to [`String`] in size with guaranteed inlining.
 ///
 /// This representation relies on pointer alignment to be able to store a discriminant bit in its
-/// inline form that will never be present in its [`String`][String] form, thus
+/// inline form that will never be present in its [`String`] form, thus
 /// giving us 24 bytes on 64-bit architectures, and 12 bytes on 32-bit, minus one bit, to encode our
 /// inline string. It uses the rest of the discriminant bit's byte to encode the string length, and
 /// the remaining bytes (23 or 11 depending on arch) to store the string data. When the available space is exceeded,
-/// it swaps itself out with a [`String`][String] containing its previous
-/// contents, relying on the discriminant bit in the [`String`][String]'s pointer to be unset, so we can
-/// store the [`String`][String] safely without taking up any extra space for a discriminant.
+/// it swaps itself out with a [`String`] containing its previous
+/// contents, relying on the discriminant bit in the [`String`]'s pointer to be unset, so we can
+/// store the [`String`] safely without taking up any extra space for a discriminant.
 ///
-/// This performs generally as well as [`String`][String] on all ops on boxed strings, and
-/// better than [`String`][String]s on inlined strings.
-///
-/// [String]: https://doc.rust-lang.org/std/string/struct.String.html
+/// This performs generally as well as [`String`] on all ops on boxed strings, and
+/// better than [`String`]s on inlined strings.
 #[derive(Debug)]
 pub struct Compact;
 
-/// A representation similar to [`Compact`][Compact] but which doesn't re-inline strings.
+/// A representation similar to [`Compact`] but which doesn't re-inline strings.
 ///
-/// This is a variant of [`Compact`][Compact] which doesn't aggressively inline strings.
-/// Where [`Compact`][Compact] automatically turns a heap allocated string back into an
-/// inlined string if it should become short enough, [`LazyCompact`][LazyCompact] keeps
+/// This is a variant of [`Compact`] which doesn't aggressively inline strings.
+/// Where [`Compact`] automatically turns a heap allocated string back into an
+/// inlined string if it should become short enough, [`LazyCompact`] keeps
 /// it heap allocated once heap allocation has occurred. If your aim is to defer heap
 /// allocation as much as possible, rather than to ensure cache locality, this is the
 /// variant you want - it won't allocate until the inline capacity is exceeded, and it
 /// also won't deallocate once allocation has occurred, which risks reallocation if the
 /// string exceeds its inline capacity in the future.
-///
-/// [Compact]: struct.Compact.html
-/// [String]: https://doc.rust-lang.org/std/string/struct.String.html
 #[derive(Debug)]
 pub struct LazyCompact;
 
-/// Marker trait for [`SmartString`][SmartString] representations.
-///
-/// See [`LazyCompact`][LazyCompact] and [`Compact`][Compact].
+/// Marker trait for [`SmartString`] representations.
 ///
-/// [SmartString]: struct.SmartString.html
-/// [Compact]: struct.Compact.html
-/// [LazyCompact]: struct.LazyCompact.html
+/// See [`LazyCompact`] and [`Compact`].
 pub trait SmartStringMode {
     /// The boxed string type for this layout.
     type BoxedString: BoxedString + From<String>;

src/iter.rs

@@ -7,9 +7,7 @@ use core::{
     str::Chars,
 };
 
-/// A draining iterator for a [`SmartString`][SmartString].
-///
-/// [SmartString]: struct.SmartString.html
+/// A draining iterator for a [`SmartString`].
 pub struct Drain<'a, Mode>(DrainCast<'a, Mode>)
 where
     Mode: SmartStringMode;