hybrid-array: basic usage docs (#27)

Adds some initial usage documentation

README.md

@@ -28,25 +28,6 @@ This crate exposes the following feature flags. The default is NO features.
 
 * `zeroize` - Implements [`Zeroize`](https://docs.rs/zeroize/latest/zeroize/trait.Zeroize.html) for `Array<T: Zeroize, U>`
 
-## Migrating from `GenericArray`
-
-*NOTE: this guide assumes a migration from `generic-array` v0.14*
-
-`hybrid-array` has been designed to largely be a drop-in replacement for
-`generic-array`, albeit with a public inner array type and significantly less
-`unsafe` code.
-
-Migrating should hopefully be relatively painless with the following
-substitutions in your `.rs` files:
-
-- Replace `generic_array` with `hybrid_array`
-- Replace `GenericArray<T, U>` with `Array<T, U>`
-- Replace `ArrayLength<T>` with `ArraySize`
-- Replace `<U as ArrayLength<T>>::ArrayType` with `<U as ArraySize>::ArrayType<T>`
-- Replace usages of the `arr![N; A, B, C]` macro with `Array([A, B, C])`
-
-If you have any questions, please [start a discussion].
-
 ## License
 
 Licensed under either of:
@@ -83,4 +64,3 @@ dual licensed as above, without any additional terms or conditions.
 [`generic-array`]: https://github.com/fizyk20/generic-array
 [rust-issue-60551]: https://github.com/rust-lang/rust/issues/60551
 [rust-issue-76560]: https://github.com/rust-lang/rust/issues/76560
-[start a discussion]: https://github.com/RustCrypto/hybrid-array/discussions

src/lib.rs

@@ -23,6 +23,44 @@
     unused_qualifications
 )]
 
+//! ## Usage
+//!
+//! The two core types in this crate are as follows:
+//!
+//! - [`Array<T, U>`]: wrapper for `[T; N]` where `U` is an [`ArraySize`] provided by [`typenum`]
+//!   whose associated [`ArraySize::ArrayType<T>`] determines the inner array size.
+//! - [`ArrayN<T, N>`]: type alias for [`Array`] which is const generic around `const N: usize`.
+//!   This provides a linkage between const generics and [`typenum`].
+//!
+//! The [`Array`] type has an inner `pub [T; N]` field, which means writing a literal can be
+//! expressed as follows:
+//!
+//! ```
+//! use hybrid_array::{Array, consts::U4};
+//!
+//! let arr: Array<u8, U4> = Array([1, 2, 3, 4]);
+//! ```
+//!
+//! ## Migrating from `GenericArray`
+//!
+//! *NOTE: this guide assumes a migration from `generic-array` v0.14*
+//!
+//! `hybrid-array` has been designed to largely be a drop-in replacement for
+//! `generic-array`, albeit with a public inner array type and significantly less
+//! `unsafe` code.
+//!
+//! Migrating should hopefully be relatively painless with the following
+//! substitutions in your `.rs` files:
+//!
+//! - Replace `generic_array` with `hybrid_array`
+//! - Replace `GenericArray<T, U>` with `Array<T, U>`
+//! - Replace `ArrayLength<T>` with `ArraySize`
+//! - Replace `<U as ArrayLength<T>>::ArrayType` with `<U as ArraySize>::ArrayType<T>`
+//! - Replace usages of the `arr![N; A, B, C]` macro with `Array([A, B, C])`
+//!
+//! If you have any questions, please
+//! [start a discussion](https://github.com/RustCrypto/hybrid-array/discussions).
+
 #[cfg(feature = "std")]
 extern crate std;
 

src/traits.rs

@@ -19,6 +19,9 @@ use typenum::Unsigned;
 /// It is implemented only for a number of types defined in [`typenum::consts`].
 pub unsafe trait ArraySize: Unsigned {
     /// Array type which corresponds to this size.
+    ///
+    /// This is always defined to be `[T; N]` where `N` is the same as
+    /// [`ArraySize::USIZE`][`typenum::Unsigned::USIZE`].
     type ArrayType<T>: AssociatedArraySize<Size = Self>
         + From<Array<T, Self>>
         + FromFn<T>