Add more API documention

Author: phil-opp

src/lib.rs

@@ -1,3 +1,12 @@
+//! Device library for the STM32F746NG discovery board.
+//!
+//! Most of the device specific code is based on the stm32f746ng [reference manual],
+//! the [STM32CubeF7] package, and the [other stm32f746ng resources].
+//!
+//! [reference manual]: https://www.st.com/resource/en/reference_manual/dm00124865.pdf
+//! [STM32CubeF7]: https://www.st.com/content/st_com/en/products/embedded-software/mcus-embedded-software/stm32-embedded-software/stm32cube-mcu-packages/stm32cubef7.html#getsoftware-scroll
+//! [other stm32f746ng resources]: https://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32f7-series/stm32f7x6/stm32f746ng.html#design-scroll
+
 #![no_std]
 #![feature(try_from)]
 #![feature(trusted_len)]

src/sd/mod.rs

@@ -1,4 +1,6 @@
-//! **This module is untested!**
+//! Provides functions to detect and initialize SD cards.
+//!
+//! **This module is currently untested!**
 
 pub use self::init::{de_init, init};
 

src/touch.rs

@@ -1,3 +1,5 @@
+//! Touchscreen functions.
+
 use crate::i2c::{self, I2C};
 use arrayvec::ArrayVec;
 
@@ -8,6 +10,7 @@ const FT5336_STATUS_REGISTER: u8 = 0x02;
 // Start locations for reading pressed touches
 const FT5336_DATA_REGISTERS: [u8; 5] = [0x03, 0x09, 0x0F, 0x15, 0x1B];
 
+/// Checks the whether the device familiy ID register contains the expected value.
 pub fn check_family_id(i2c_3: &mut I2C) -> Result<(), i2c::Error> {
     i2c_3.connect::<u8, _>(FT5336_ADDRESS, |mut conn| {
         // read and check device family ID
@@ -17,11 +20,13 @@ pub fn check_family_id(i2c_3: &mut I2C) -> Result<(), i2c::Error> {
 }
 
 #[derive(Debug, Clone, Copy)]
+/// Represents a touch point on the display at coordinates (x,y).
 pub struct Touch {
     pub x: u16,
     pub y: u16,
 }
 
+/// Returns a list of active touch points.
 pub fn touches(i2c_3: &mut I2C) -> Result<ArrayVec<[Touch; 5]>, i2c::Error> {
     let mut touches = ArrayVec::new();
     i2c_3.connect::<u8, _>(FT5336_ADDRESS, |mut conn| {