From 7a65556bc7a4485c8f8b9d3671084b354993aaa5 Mon Sep 17 00:00:00 2001
From: OrganomagnesiumHalide
 <99297401+OrganomagnesiumHalide@users.noreply.github.com>
Date: Thu, 9 Feb 2023 17:07:10 -0800
Subject: [PATCH] Added documentation to #[entry] and to the readme

While the project does have examples, even a simple example such as
blinky doesn't really cover how to get started if you don't want to use
a template.
---
 boards/arduino_nano_connect/src/lib.rs | 11 ++++--
 boards/rp-pico/README.md               | 26 +++++++++++++
 boards/rp-pico/src/lib.rs              | 52 ++++++++++++++++++++++++++
 3 files changed, 85 insertions(+), 4 deletions(-)

diff --git a/boards/arduino_nano_connect/src/lib.rs b/boards/arduino_nano_connect/src/lib.rs
index 2412616..069f6fd 100644
--- a/boards/arduino_nano_connect/src/lib.rs
+++ b/boards/arduino_nano_connect/src/lib.rs
@@ -8,16 +8,19 @@ pub use rp2040_hal::entry;
 /// The linker will place this boot block at the start of our program image. We
 /// need this to help the ROM bootloader get our code up and running.
 ///
-/// According to
-/// https://store.arduino.cc/products/arduino-nano-rp2040-connect
+/// According to [the Arduino store]
 /// the board should contain a AT25SF128A flash chip. But
-/// there are reports of board with different flash chips,
+/// there are [reports] of board with different flash chips,
 /// where the boot loader BOOT_LOADER_AT25SF128A does not
-/// work. (https://github.com/rp-rs/rp-hal/issues/503)
+/// work. 
 ///
 /// Therefore, the generic boot loader is used by default. For a specific
 /// board, the flash performance can be increased by switching to the
 /// matching boot loader.
+/// 
+/// [the Arduino store]: https://store.arduino.cc/products/arduino-nano-rp2040-connect
+/// [reports]: https://github.com/rp-rs/rp-hal/issues/503
+/// 
 #[cfg(feature = "boot2")]
 #[link_section = ".boot2"]
 #[no_mangle]
diff --git a/boards/rp-pico/README.md b/boards/rp-pico/README.md
index 6804efe..302f8f1 100644
--- a/boards/rp-pico/README.md
+++ b/boards/rp-pico/README.md
@@ -54,6 +54,32 @@ $ cargo install elf2uf2-rs
 ```
 then try repeating the `cargo run` command above.
 
+### From Scratch
+
+To start a basic project from scratch, create a project using `cargo new project-name`. Within the
+project directory, run `cargo add rp-pico`, `cargo add cortex-m-rt`, and `cargo add panic-halt`. The
+first command will this HAL (Hardware Abstraction Layer), the second is required for the `#[entry]` macro, and _panic-halt_ creates a simple panic function, which just halts.
+
+You'll also need to copy the cargo config file from the [repo](https://github.com/rp-rs/rp-hal-boards/blob/main/.cargo/config). It specifies the target and optimizing flags to the linker. You'll also need to copy [_memory.x_](https://github.com/rp-rs/rp-hal-boards/blob/main/memory.x) to your project root. This file tells the linker the flash and RAM layout, so it won't clobber the bootloader or write to an out of bounds memory address. 
+
+The simplest working example, which does nothing except loop forever, is:
+
+```rust
+#![no_std]
+#![no_main]
+use rp_pico::entry;
+use panic_halt as _;
+#[entry]
+fn see_doesnt_have_to_be_called_main() -> ! {
+  loop {}
+}
+```
+
+It can be placed in _/src/main.rs_. 
+
+You can use `cargo run` to compile and install it. 
+**Note**: You won't see any activity since this program does nothing. You can use the examples provided
+to add more functionality. 
 ### [pico_blinky](./examples/pico_blinky.rs)
 
 Flashes the Pico's on-board LED on and off.
diff --git a/boards/rp-pico/src/lib.rs b/boards/rp-pico/src/lib.rs
index 06f2a36..ac13aa5 100644
--- a/boards/rp-pico/src/lib.rs
+++ b/boards/rp-pico/src/lib.rs
@@ -1,9 +1,61 @@
 #![no_std]
 
+//! A Hardware Abstraction Layer for the Raspberry Pi Pico.
+//! 
+//! This crate serves as a HAL (Hardware Abstraction Layer) for the Raspberry Pi Pico. Since the Raspberry Pi Pico
+//! is based on the RP2040 chip, it re-exports the [rp2040_hal] crate which contains the tooling to work with the 
+//! rp2040 chip.
+//! 
+//! # Examples:
+//! 
+//! The following example turns on the onboard LED. Note that most of the logic works through the [rp2040_hal] crate.
+//! ```
+//! #![no_main]
+//! use rp_pico::entry;
+//! use panic_halt as _;
+//! use embedded_hal::digital::v2::OutputPin;
+//! use rp_pico::hal::pac;
+//! use rp_pico::hal;
+
+//! #[entry]
+//! fn does_not_have_to_be_main() -> ! {
+//!   let mut pac = pac::Peripherals::take().unwrap();
+//!   let sio = hal::Sio::new(pac.SIO);
+//!   let pins = rp_pico::Pins::new(
+//!        pac.IO_BANK0,
+//!        pac.PADS_BANK0,
+//!        sio.gpio_bank0,
+//!        &mut pac.RESETS,
+//!   );
+//!   let mut led_pin = pins.led.into_push_pull_output();
+//!   led_pin.set_high().unwrap();
+//!   loop {
+//!   }
+//! }
+//! ```
+
+
 pub extern crate rp2040_hal as hal;
 
 #[cfg(feature = "rt")]
 extern crate cortex_m_rt;
+
+/// The `entry` macro declares the starting function to the linker. 
+/// This is similar to the `main` function in console applications.
+/// 
+/// It is based on the [cortex_m_rt](https://docs.rs/cortex-m-rt/latest/cortex_m_rt/attr.entry.html) crate.
+/// 
+/// # Examples 
+/// ```
+/// #![no_std]
+/// #![no_main]
+/// use rp_pico::entry;
+/// #[entry]
+/// fn you_can_use_a_custom_main_name_here() -> ! {
+///   loop {}
+/// }
+/// ```
+
 #[cfg(feature = "rt")]
 pub use hal::entry;