diff --git a/avr-hal-generic/src/lib.rs b/avr-hal-generic/src/lib.rs
index c9d5e3e66c..3b7cb0527e 100644
--- a/avr-hal-generic/src/lib.rs
+++ b/avr-hal-generic/src/lib.rs
@@ -1,6 +1,38 @@
 #![no_std]
 #![cfg_attr(avr_hal_asm_macro, feature(asm_experimental_arch))]
 #![cfg_attr(not(avr_hal_asm_macro), feature(llvm_asm))]
+//! Defines the internal API used to generate the per-device external API
+//! (user-facing) in the HAL crates.
+//!
+//! # Macro Design (WIP)
+//!
+//! As part of an effort to make the macros here more maintainable and less
+//! repetitive, they are being restructured module-by-module. Currently revised
+//! modules are:
+//! - [`adc`]
+//! - [`port`]
+//!
+//! The general guiding principals are:
+//! 1. What goes inside the macro invocation should look like regular code as
+//! much as possible;
+//! 2. Information related to groups of implementations of a feature should be
+//! encoded as alternative matchers in the macro, rather than by introducing
+//! many metavariables that each invocation will need to repeat;
+//!    As an example of such information, take the ADC's reference voltage.  All
+//! Atmega processors can be abstracted with the same definition of the
+//! `ReferenceVoltage` type, but Attiny processors differ among themselves and
+//! also from the Atmega implementation. Rather than leave that type up to the
+//! invocation, write one fully general matcher and write smaller matchers that
+//! expand to pre-filled versions of the former. The HAL crates then use these
+//! as much as possible, falling back only when there is singular hardware
+//! that would need its own matcher but would use it only once.
+//! 3. Information unique to each implementation should be left to the
+//! invocation, but make the macro smart enough to avoid repeating ourselves.
+//!    An example of this is the mapping between ADC channels and pins. The best
+//! scenario here is a mapping like `<channel> = <pin>`, maybe `<channel>:
+//! <type> = <pin>`, if there's more information needed to encode the mapping.
+//! [`paste::paste`] can be used for gluing the information into adequate
+//! identifiers.
 
 pub use embedded_hal_v0 as hal;