Document support for register arrays in each macro

Since stm32ral doesn't have register arrays, I'm using prose and
pseudo-code to document each macro's support for register arrays. This
seemed to be today's simplest way to document the features for users.

I have another commit that implements a hidden module with a RAL-like
API and register arrays. Documentation examples then reference this
hidden module to demonstrate the register array feature. But, it adds
more code (could be shared with the tests), and it resulted in
inconsistent documentation examples when compared to the STM examples.

1 files changed, 24 insertions, 4 deletions

diff --git a/src/lib.rs b/src/lib.rs
index c65e94b..bcf0370 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -194,6 +194,10 @@ impl<T: Copy> UnsafeWORegister<T> {
 /// # }
 /// ```
 ///
+/// To support register arrays, each macro form also supports one or more array indices after the
+/// register. For example, `write_reg!(stm32ral::gpio, gpioa, ODR[2], 42);` writes the value 42 to
+/// the third register in an `ODR` register array.
+///
 /// # Usage
 /// Like `modify_reg!`, this macro can be used in two ways, either with a single value to write to
 /// the whole register, or with multiple fields each with their own value.
@@ -203,7 +207,8 @@ impl<T: Copy> UnsafeWORegister<T> {
 /// * a reference to the instance of that peripheral: 'gpioa' (anything which dereferences to
 ///   `RegisterBlock`, such as `Instance`, `&Instance`, `&RegisterBlock`, or
 ///   `*const RegisterBlock`),
-/// * the register you wish you access: `MODER` (a field on the `RegisterBlock`).
+/// * the register (and offset, for arrays) you wish you access: `MODER` (a field on the
+///   `RegisterBlock`).
 ///
 /// In the single-value usage, the final argument is just the value to write:
 /// ```rust,no_run
@@ -313,6 +318,10 @@ macro_rules! write_reg {
 /// # }
 /// ```
 ///
+/// To support register arrays, each macro form also supports one or more array indices after the
+/// register. For example, `modify_reg!(stm32ral::gpio, gpioa, ODR[2], |reg| reg | (1<<3));` sets
+/// a high bit in the third register of an `ODR` register array.
+///
 /// # Usage
 /// Like `write_reg!`, this macro can be used in two ways, either with a modification of the entire
 /// register, or by specifying which fields to change and what value to change them to.
@@ -322,7 +331,8 @@ macro_rules! write_reg {
 /// * a reference to the instance of that peripheral: 'gpioa' (anything which dereferences to
 ///   `RegisterBlock`, such as `Instance`, `&Instance`, `&RegisterBlock`, or
 ///   `*const RegisterBlock`),
-/// * the register you wish you access: `MODER` (a field on the `RegisterBlock`).
+/// * the register (and offset, for arrays) you wish you access: `MODER` (a field on the
+///   `RegisterBlock`).
 ///
 /// In the whole-register usage, the final argument is a closure that accepts the current value
 /// of the register and returns the new value to write:
@@ -453,6 +463,10 @@ macro_rules! modify_reg {
 /// # }
 /// ```
 ///
+/// To support register arrays, each macro form also supports one or more array indices after the
+/// register. For example, `read_reg!(stm32ral::gpio, gpioa, ODR[2]);` reads from the third
+/// register of an `ODR` register array.
+///
 /// # Usage
 /// Like `write_reg!`, this macro can be used multiple ways, either reading the entire register or
 /// reading a one or more fields from it and potentially performing a comparison with one field.
@@ -462,7 +476,8 @@ macro_rules! modify_reg {
 /// * a reference to the instance of that peripheral: 'gpioa' (anything which dereferences to
 ///   `RegisterBlock`, such as `Instance`, `&Instance`, `&RegisterBlock`, or
 ///   `*const RegisterBlock`),
-/// * the register you wish to access: `IDR` (a field on the `RegisterBlock`).
+/// * the register (and offset, for arrays) you wish to access: `IDR` (a field on the
+///   `RegisterBlock`).
 ///
 /// In the whole-register usage, the macro simply returns the register's value:
 /// ```rust,no_run
@@ -567,6 +582,10 @@ macro_rules! read_reg {
 /// # }
 /// ```
 ///
+/// To support register arrays, each macro form also supports one or more array indices after
+/// the register. For example, `reset_reg!(stm32ral::gpio, gpioa, GPIOA, ODR[2]);` resets the
+/// third register in an `ODR` register array.
+///
 /// # Usage
 /// Like `write_reg!`, this macro can be used in two ways, either resetting the entire register
 /// or just resetting specific fields within in. The register or fields are written with their
@@ -578,7 +597,8 @@ macro_rules! read_reg {
 ///   `RegisterBlock`, such as `Instance`, `&Instance`, `&RegisterBlock`, or
 ///   `*const RegisterBlock`),
 /// * the module for the instance of that peripheral: `GPIOA`,
-/// * the register you wish to access: `MODER` (a field on the `RegisterBlock`).
+/// * the register (and offset, for arrays) you wish to access: `MODER` (a field on the
+///   `RegisterBlock`).
 ///
 /// In the whole-register usage, that's it:
 /// ```rust,no_run