move readme explanation into the crate docs.

README.md

@@ -1,91 +1,3 @@
 # `gba`
 
 # [Docs.rs Documentation](https://docs.rs/gba)
-
-## How To Make Your Own GBA Project Using This Crate
-
-This will require the use of Nightly Rust. Any recent-ish version of Nightly should be fine.
-
-### Get ARM Binutils
-
-You'll need the ARM version of the GNU binutils in your path, specifically the linker (`arm-none-eabi-ld`).
-
-Linux folks can use the package manager. Mac and Windows folks can use the [ARM Website](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain).
-
-### Run `rustup component add rust-src`
-
-This makes rustup keep the standard library source code on hand, which is necessary for `build-std` to work.
-
-### Create `.cargo/config.toml`
-
-You should set up your project's cargo config like so:
-
-```toml
-[build]
-target = "thumbv4t-none-eabi"
-
-[unstable]
-build-std = ["core"]
-
-[target.thumbv4t-none-eabi]
-runner = "mgba-qt"
-rustflags = ["-Clink-arg=-Tlink_scripts/mono_boot.ld"]
-```
-
-This sets the default build target to be `thumbv4t-none-eabi` using the unstable `build-std` cargo feature.
-
-Also, this sets `cargo run` to run the binary as an argument to `mgba-qt`.
-If you're on windows then your copy of mGBA will be called "mgba.exe" instead.
-
-Also, this sets [mono_boot.ld](link_scripts/mono_boot.ld) as the linker script.
-You'll need to copy this into your project.
-If you save it to another location, adjust the path accordingly.
-
-### Make Your Executables
-
-At this point you can make a `bin` or an `example`.
-
-Every executable will need to be `no_std` and `no_main`.
-Place these at the top of the file:
-
-```rust
-#![no_std]
-#![no_main]
-```
-
-Every executable will need a panic handler defined, even if your code can't actually panic.
-A minimal panic handler looks like this:
-
-```rust
-#[panic_handler]
-fn panic_handler(_: &core::panic::PanicInfo) -> ! {
-  loop {}
-}
-```
-
-Every executable will need a `main` function defined.
-We used the `no_main` attribute on the executable so that Rust will allow us to use a non-standard function signature:
-
-```rust
-#[no_mangle]
-extern "C" fn main() -> ! {
-  loop {}
-}
-```
-
-### Optional: Use `objcopy` and `gbafix`
-
-The `cargo build` will produce ELF files, which mGBA can run directly.
-
-If you want to run your program on real hardware you'll need to:
-
-1) `objcopy` the raw binary out of the ELF into its own file.
-2) Use `gbafix` to give the file appropriate header data to that file.
-
-You can get `gbafix` through cargo: `cargo install gbafix`.
-
-## Other GBA Crates
-
-This crate provides a largely "unmanaged" interaction with the GBA's hardware.
-If you would like an API that use the borrow checker to guide you more,
-the [agb](https://docs.rs/agb) crate might be what you want.

src/lib.rs

@@ -3,6 +3,85 @@
 #![feature(asm_const)]
 #![feature(isa_attribute)]
 #![feature(naked_functions)]
+#![warn(missing_docs)]
+
+//! A crate for GBA development.
+//!
+//! ## How To Make Your Own GBA Project Using This Crate
+//!
+//! This will require the use of Nightly Rust. Any recent-ish version of Nightly
+//! should be fine.
+//!
+//! [arm-download]:
+//!     https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain
+//!
+//! * **Get The ARM Binutils:** You'll need the ARM version of the GNU binutils
+//!   in your path, specifically the linker (`arm-none-eabi-ld`). Linux folks
+//!   can use the package manager. Mac and Windows folks can use the [ARM
+//!   Website][arm-download].
+//! * **Run `rustup component add rust-src`:** This makes rustup keep the
+//!   standard library source code on hand, which is necessary for `build-std`
+//!   to work.
+//! * **Create A `.cargo/config.toml`:** You'll want to set up a file to provide
+//!   all the right default settings so that a basic `cargo build` and `cargo
+//!   run` will "just work". Something like the following is what you probably
+//!   want.
+//!
+//! ```toml
+//! [build]
+//! target = "thumbv4t-none-eabi"
+//!
+//! [unstable]
+//! build-std = ["core"]
+//!
+//! [target.thumbv4t-none-eabi]
+//! runner = "mgba-qt"
+//! rustflags = ["-Clink-arg=-Tlinker_scripts/mono_boot.ld"]
+//! ```
+//!
+//! * **Make Your Executables:** At this point you can make a `bin` or an
+//!   `example` file. Every executable will need to be `#![no_std]` and
+//!   `#![no_main]`. They will also need a `#[panic_handler]` defined, as well
+//!   as a `#[no_mangle] extern "C" main() -> !` function, which is what the
+//!   assembly runtime will call to start your Rust program after it fully
+//!   initializes the system.
+//!
+//! ```rust
+//! #![no_std]
+//! #![no_main]
+//!
+//! #[panic_handler]
+//! fn panic_handler(_: &core::panic::PanicInfo) -> ! {
+//!   loop {}
+//! }
+//!
+//! #[no_mangle]
+//! extern "C" fn main() -> ! {
+//!   loop {}
+//! }
+//! ```
+//!
+//! * **Optional: Use `objcopy` and `gbafix`:** The `cargo build` will produce
+//!   ELF files, which mGBA can run directly. If you want to run your program on
+//!   real hardware you'll need to first `objcopy` the raw binary out of the ELF
+//!   into its own file, then Use `gbafix` to give an appropriate header to the
+//!   file. `objcopy` is part of the ARM binutils you already installed, it
+//!   should be named `arm-none-eabi-objcopy`. You can get `gbafix` through
+//!   cargo: `cargo install gbafix`.
+//!
+//! ## Other GBA-related Crates
+//!
+//! This crate provides a largely "unmanaged" interaction with the GBA's
+//! hardware. If you would like an API that use the borrow checker to guide you
+//! more, the [agb](https://docs.rs/agb) crate might be what you want.
+//!
+//! ## Safety
+//!
+//! All safety considerations for the crate assume that you're building for the
+//! `thumbv4t-none-eabi` or `armv4t-none-eabi` targets, using the provided
+//! linker script, and then running the code on a GBA. While it's possible to
+//! break any of these assumptions, if you do that some or all of the code
+//! provided by this crate may become unsound.
 
 mod macros;