Add some documentation

src/boot_loader_name.rs

@@ -1,4 +1,8 @@
 
+/// This Tag contains the name of the bootloader that is booting the kernel.
+///
+/// The name is a normal C-style UTF-8 zero-terminated string that can be
+/// obtained via the `name` method.
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)] // only repr(C) would add unwanted padding before first_section
 pub struct BootLoaderNameTag {
@@ -8,6 +12,16 @@ pub struct BootLoaderNameTag {
 }
 
 impl BootLoaderNameTag {
+    /// Read the name of the bootloader that is booting the kernel.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// if let Some(tag) = boot_info.boot_loader_name_tag() {
+    ///     let name = tag.name();
+    ///     // println!("Booted by: {:?}!", name);
+    /// }
+    /// ```
     pub fn name(&self) -> &str {
         use core::{mem,str,slice};
         unsafe {

src/command_line.rs

@@ -1,4 +1,7 @@
-
+/// This Tag contains the command line string.
+///
+/// The string is a normal C-style UTF-8 zero-terminated string that can be
+/// obtained via the `command_line` method.
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)] // only repr(C) would add unwanted padding before first_section
 pub struct CommandLineTag {
@@ -8,6 +11,16 @@ pub struct CommandLineTag {
 }
 
 impl CommandLineTag {
+    /// Read the command line string that is being passed to the booting kernel.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// if let Some(tag) = boot_info.command_line_tag() {
+    ///     let command_line = tag.command_line();
+    ///     // println!("Command line: {:?}!", command_line);
+    /// }
+    /// ```
     pub fn command_line(&self) -> &str {
         use core::{mem,str,slice};
         unsafe {

src/elf_sections.rs

@@ -1,5 +1,8 @@
 use header::Tag;
 
+/// This tag contains section header table from an ELF kernel.
+///
+/// The sections iterator is provided via the `sections` method.
 #[derive(Debug)]
 pub struct ElfSectionsTag {
     inner: *const ElfSectionsTagInner,
@@ -25,6 +28,19 @@ struct ElfSectionsTagInner {
 }
 
 impl ElfSectionsTag {
+    /// Get an iterator of loaded ELF sections.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// if let Some(elf_tag) = boot_info.elf_sections_tag() {
+    ///     let mut total = 0;
+    ///     for section in elf_tag.sections() {
+    ///         println!("Section: {:?}", section);
+    ///         total += 1;
+    ///     }
+    /// }
+    /// ```
     pub fn sections(&self) -> ElfSectionIter {
         let string_section_offset = (self.get().shndx * self.get().entry_size) as isize;
         let string_section_ptr = unsafe {
@@ -48,6 +64,7 @@ impl ElfSectionsTag {
     }
 }
 
+/// An iterator over some elf sections.
 #[derive(Clone, Debug)]
 pub struct ElfSectionIter {
     current_section: *const u8,
@@ -80,6 +97,7 @@ impl Iterator for ElfSectionIter {
     }
 }
 
+/// A single generic ELF Section.
 #[derive(Debug)]
 pub struct ElfSection {
     inner: *const u8,
@@ -119,6 +137,7 @@ struct ElfSectionInner64 {
 }
 
 impl ElfSection {
+    /// Get the section type as a `ElfSectionType` enum variant.
     pub fn section_type(&self) -> ElfSectionType {
         match self.get().typ() {
             0 => ElfSectionType::Unused,
@@ -139,10 +158,12 @@ impl ElfSection {
         }
     }
 
+    /// Get the "raw" section type as a `u32`
     pub fn section_type_raw(&self) -> u32 {
         self.get().typ()
     }
 
+    /// Read the name of the section from the string table and an offset.
     pub fn name(&self) -> &str {
         use core::{str, slice};
 
@@ -160,26 +181,39 @@ impl ElfSection {
         str::from_utf8(unsafe { slice::from_raw_parts(name_ptr, strlen) }).unwrap()
     }
 
+    /// Get the physical start address of the section.
     pub fn start_address(&self) -> u64 {
         self.get().addr()
     }
 
+    /// Get the physical end address of the section.
+    ///
+    /// This is the same as doing `section.start_address() + section.size()`
     pub fn end_address(&self) -> u64 {
         self.get().addr() + self.get().size()
     }
 
+    /// This member gives the section's size in bytes.
     pub fn size(&self) -> u64 {
         self.get().size()
     }
 
+    /// Get the sections address alignment constraints.
+    ///
+    /// That is, the value of `start_address` must be congruent to 0,
+    /// modulo the value of `addrlign`. Currently, only 0 and positive
+    /// integral powers of two are allowed. Values 0 and 1 mean the section has no
+    /// alignment constraints.
     pub fn addralign(&self) -> u64 {
         self.get().addralign()
     }
 
+    /// Get the sections flags.
     pub fn flags(&self) -> ElfSectionFlags {
         ElfSectionFlags::from_bits_truncate(self.get().flags())
     }
 
+    /// Check if the `ALLOCATED` flag is set in the section flags.
     pub fn is_allocated(&self) -> bool {
         self.flags().contains(ElfSectionFlags::ALLOCATED)
     }
@@ -268,29 +302,72 @@ impl ElfSectionInner for ElfSectionInner64 {
     }
 }
 
+/// An enum abstraction over raw ELF section types.
 #[derive(PartialEq, Eq, Debug, Copy, Clone)]
 #[repr(u32)]
 pub enum ElfSectionType {
+    /// This value marks the section header as inactive; it does not have an
+    /// associated section. Other members of the section header have undefined
+    /// values.
     Unused = 0,
+
+    /// The section holds information defined by the program, whose format and
+    /// meaning are determined solely by the program.
     ProgramSection = 1,
+
+    /// This section holds a symbol table.
     LinkerSymbolTable = 2,
+
+    /// The section holds a string table.
     StringTable = 3,
+
+    /// The section holds relocation entries with explicit addends, such as type
+    /// Elf32_Rela for the 32-bit class of object files. An object file may have
+    /// multiple relocation sections.
     RelaRelocation = 4,
+
+    /// The section holds a symbol hash table.
     SymbolHashTable = 5,
+
+    /// The section holds information for dynamic linking.
     DynamicLinkingTable = 6,
+
+    /// This section holds information that marks the file in some way.
     Note = 7,
+
+    /// A section of this type occupies no space in the file but otherwise resembles
+    /// SHT_PROGBITS. Although this section contains no bytes, the
+    /// sh_offset member contains the conceptual file offset.
     Uninitialized = 8,
+
+    /// The section holds relocation entries without explicit addends, such as type
+    /// Elf32_Rel for the 32-bit class of object files. An object file may have
+    /// multiple relocation sections.
     RelRelocation = 9,
+
+    /// This section type is reserved but has unspecified semantics.
     Reserved = 10,
+
+    /// This section holds a symbol table.
     DynamicLoaderSymbolTable = 11,
+
+    /// Values in this inclusive range are reserved for environment-specific semantics.
     EnvironmentSpecific = 0x6000_0000,
+
+    /// Values in this inclusive range are reserved for processor-specific semantics.
     ProcessorSpecific = 0x7000_0000,
 }
 
 bitflags! {
+    /// ELF Section bitflags.
     pub struct ElfSectionFlags: u64 {
+        /// The section contains data that should be writable during program execution.
         const WRITABLE = 0x1;
+
+        /// The section occupies memory during the process execution.
         const ALLOCATED = 0x2;
+
+        /// The section contains executable machine instructions.
         const EXECUTABLE = 0x4;
         // plus environment-specific use at 0x0F000000
         // plus processor-specific use at 0xF0000000

src/framebuffer.rs

@@ -2,40 +2,79 @@ use header::Tag;
 use ::Reader;
 use core::slice;
 
+/// The VBE Framebuffer information Tag.
 #[derive(Debug, PartialEq)]
 pub struct FramebufferTag<'a> {
+    /// Contains framebuffer physical address.
+    ///
+    /// This field is 64-bit wide but bootloader should set it under 4GiB if
+    /// possible for compatibility with payloads which aren’t aware of PAE or
+    /// amd64.
     pub address: u64,
+
+    /// Contains the pitch in bytes.
     pub pitch: u32,
+
+    /// Contain framebuffer width in pixels.
     pub width: u32,
+
+    /// Contain framebuffer height in pixels.
     pub height: u32,
+
+    /// Contains number of bits per pixel.
     pub bpp: u8,
+
+    /// The type of framebuffer, one of: Indexed, RGB or Text.
     pub buffer_type: FramebufferType<'a>
 }
 
+/// The type of framebuffer.
 #[derive(Debug, PartialEq)]
 pub enum FramebufferType<'a> {
+    /// Indexed color.
     Indexed {
+        #[allow(missing_docs)]
         palette: &'a [FramebufferColor]
     },
+
+    /// Direct RGB color.
+    #[allow(missing_docs)]
     RGB {
         red: FramebufferField,
         green: FramebufferField,
         blue: FramebufferField
     },
+
+    /// EGA Text.
+    ///
+    /// In this case the framebuffer width and height are expressed in
+    /// characters and not in pixels.
+    ///
+    /// The bpp is equal 16 (16 bits per character) and pitch is expressed in bytes per text line.
     Text
 }
 
+/// An RGB color type field.
 #[derive(Debug, PartialEq)]
 pub struct FramebufferField {
+    /// Color field position.
     pub position: u8,
+
+    /// Color mask size.
     pub size: u8
 }
 
+/// A framebuffer color descriptor in the palette.
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[repr(C, packed)]
 pub struct FramebufferColor {
+    /// The amount of Red.
     pub red: u8,
+
+    /// The amount of Green.
     pub green: u8,
+
+    /// The amount of Blue.
     pub blue: u8
 }
 

src/lib.rs

@@ -1,5 +1,25 @@
 #![no_std]
 #![deny(missing_debug_implementations)]
+#![deny(missing_docs)]
+
+//! An experimental Multiboot 2 crate for ELF-64/32 kernels.
+//!
+//! The GNU Multiboot specification aims provide a standardised
+//! method of sharing commonly used information about the host machine at
+//! boot time.
+//!
+//! # Examples
+//!
+//! ```
+//! use multiboot2::load;
+//!
+//! // The Multiboot 2 specification dictates that the machine state after the
+//! // bootloader finishes its job will be that the boot information struct pointer
+//! // is stored in the `EBX` register.
+//! let multiboot_info_ptr: u32;
+//! unsafe { asm!("mov $2, %ebx" : "=r"(multiboot_info_ptr)) };
+//! let boot_info = unsafe { load(multiboot_info_ptr) };
+//! ```
 
 use core::fmt;
 
@@ -27,6 +47,21 @@ mod rsdp;
 mod framebuffer;
 mod vbe_info;
 
+/// Load the multiboot boot information struct from an address.
+///
+/// This is the same as `load_with_offset` but the offset is ommitted and set
+/// to zero.
+///
+/// Examples
+///
+/// ```
+/// use multiboot::load;
+///
+/// fn kmain(multiboot_info_ptr: u32) {
+///     let boot_info = load(ptr as usize);
+///     println!("{:?}", boot_info);
+/// }
+/// ```
 pub unsafe fn load(address: usize) -> BootInformation {
     assert_eq!(0, address & 0b111);
     let multiboot = &*(address as *const BootInformationInner);
@@ -35,6 +70,17 @@ pub unsafe fn load(address: usize) -> BootInformation {
     BootInformation { inner: multiboot, offset: 0 }
 }
 
+/// Load the multiboot boot information struct from an address at an offset.
+///
+/// Examples
+///
+/// ```
+/// use multiboot::load;
+///
+/// let ptr = 0xDEADBEEF as *const _;
+/// let boot_info = load_with_offset(ptr as usize, 0xCAFEBABE);
+/// println!("{:?}", boot_info);
+/// ```
 pub unsafe fn load_with_offset(address: usize, offset: usize) -> BootInformation {
     if !cfg!(test) {
         assert_eq!(0, address & 0b111);
@@ -46,6 +92,7 @@ pub unsafe fn load_with_offset(address: usize, offset: usize) -> BootInformation
     BootInformation { inner: multiboot, offset: offset }
 }
 
+/// A Multiboot 2 Boot Information struct.
 pub struct BootInformation {
     inner: *const BootInformationInner,
     offset: usize,
@@ -58,52 +105,70 @@ struct BootInformationInner {
 }
 
 impl BootInformation {
+    /// Get the start address of the boot info.
     pub fn start_address(&self) -> usize {
         self.inner as usize
     }
 
+    /// Get the end address of the boot info.
+    ///
+    /// This is the same as doing:
+    ///
+    /// ```
+    /// let end_addr = boot_info.start_address() + boot_info.size();
+    /// ```
     pub fn end_address(&self) -> usize {
         self.start_address() + self.total_size()
     }
 
+    /// Get the total size of the boot info struct.
     pub fn total_size(&self) -> usize {
         self.get().total_size as usize
     }
 
+    /// Search for the ELF Sections tag.
     pub fn elf_sections_tag(&self) -> Option<ElfSectionsTag> {
         self.get_tag(9).map(|tag| unsafe {
             elf_sections::elf_sections_tag(tag, self.offset)
         })
     }
 
+    /// Search for the Memory map tag.
     pub fn memory_map_tag<'a>(&'a self) -> Option<&'a MemoryMapTag> {
         self.get_tag(6).map(|tag| unsafe { &*(tag as *const Tag as *const MemoryMapTag) })
     }
 
+    /// Get an iterator of all module tags.
     pub fn module_tags(&self) -> ModuleIter {
         module::module_iter(self.tags())
     }
 
+    /// Search for the BootLoader name tag.
     pub fn boot_loader_name_tag<'a>(&'a self) -> Option<&'a BootLoaderNameTag> {
         self.get_tag(2).map(|tag| unsafe { &*(tag as *const Tag as *const BootLoaderNameTag) })
     }
 
+    /// Search for the Memory map tag.
     pub fn command_line_tag<'a>(&'a self) -> Option<&'a CommandLineTag> {
         self.get_tag(1).map(|tag| unsafe { &*(tag as *const Tag as *const CommandLineTag) })
     }
 
+    /// Search for the VBE framebuffer tag.
     pub fn framebuffer_tag<'a>(&'a self) -> Option<FramebufferTag<'a>> {
         self.get_tag(8).map(|tag| framebuffer::framebuffer_tag(tag))
     }
 
+    /// Search for the (ACPI 1.0) RSDP tag.
     pub fn rsdp_v1_tag<'a>(&self) -> Option<&'a RsdpV1Tag> {
         self.get_tag(14).map(|tag| unsafe { &*(tag as *const Tag as *const RsdpV1Tag) })
     }
 
+    /// Search for the (ACPI 2.0 or later) RSDP tag.
     pub fn rsdp_v2_tag<'a>(&'a self) -> Option<&'a RsdpV2Tag> {
         self.get_tag(15).map(|tag| unsafe { &*(tag as *const Tag as *const RsdpV2Tag) })
     }
 
+    /// Search for the VBE information tag.
     pub fn vbe_info_tag(&self) -> Option<&'static VBEInfoTag> {
         self.get_tag(7).map(|tag| unsafe { &*(tag as *const Tag as *const VBEInfoTag) })
     }

src/memory_map.rs

@@ -1,5 +1,15 @@
 use core::marker::PhantomData;
 
+/// This Tag provides an initial host memory map.
+///
+/// The map provided is guaranteed to list all standard RAM that should be
+/// available for normal use. This type however includes the regions occupied
+/// by kernel, mbi, segments and modules. Kernel must take care not to
+/// overwrite these regions.
+///
+/// This tag may not be provided by some boot loaders on EFI platforms if EFI
+/// boot services are enabled and available for the loaded image
+/// (EFI boot services not terminated tag exists in Multiboot2 information structure).   
 #[derive(Debug)]
 #[repr(C)]
 pub struct MemoryMapTag {
@@ -11,6 +21,7 @@ pub struct MemoryMapTag {
 }
 
 impl MemoryMapTag {
+    /// Return an iterator over all AVAILABLE marked memory areas.
     pub fn memory_areas(&self) -> MemoryAreaIter {
         let self_ptr = self as *const MemoryMapTag;
         let start_area = (&self.first_area) as *const MemoryArea;
@@ -23,6 +34,7 @@ impl MemoryMapTag {
     }
 }
 
+/// A memory area entry descriptor.
 #[derive(Debug)]
 #[repr(C)]
 pub struct MemoryArea {
@@ -33,18 +45,22 @@ pub struct MemoryArea {
 }
 
 impl MemoryArea {
+    /// The start address of the memory region.
     pub fn start_address(&self) -> u64 {
         self.base_addr
     }
 
+    /// The end address of the memory region.
     pub fn end_address(&self) -> u64 {
         (self.base_addr + self.length)
     }
 
+    /// The size, in bytes, of the memory region.
     pub fn size(&self) -> u64 {
         self.length
     }
 
+    /// The type of the memory region.
     pub fn typ(&self) -> MemoryAreaType {
         match self.typ {
             1 => MemoryAreaType::Available,
@@ -56,15 +72,26 @@ impl MemoryArea {
     }
 }
 
+/// An enum of possible reported region types.
 #[derive(Debug, PartialEq, Eq)]
 pub enum MemoryAreaType {
+    /// A reserved area that must not be used.
     Reserved,
+
+    /// Available memory free to be used by the OS.
     Available,
+
+    /// Usable memory holding ACPI information.
     AcpiAvailable,
+
+    /// Reserved memory which needs to be preserved on hibernation.
     ReservedHibernate,
+
+    /// Memory which is occupied by defective RAM modules.
     Defective,
 }
 
+/// An area over Available memory areas.
 #[derive(Clone, Debug)]
 pub struct MemoryAreaIter<'a> {
     current_area: u64,

src/module.rs

@@ -1,5 +1,7 @@
 use header::{Tag, TagIter};
 
+/// This tag indicates to the kernel what boot module was loaded along with
+/// the kernel image, and where it can be found. 
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)]
 pub struct ModuleTag {
@@ -14,6 +16,7 @@ impl ModuleTag {
     // The multiboot specification defines the module str
     // as valid utf-8, therefore this function produces
     // defined behavior
+    /// Get the name of the module.
     pub fn name(&self) -> &str {
         use core::{mem,str,slice};
         let strlen = self.size as usize - mem::size_of::<ModuleTag>();
@@ -23,10 +26,12 @@ impl ModuleTag {
         }
     }
 
+    /// Start address of the module.
     pub fn start_address(&self) -> u32 {
         self.mod_start
     }
 
+    /// End address of the module
     pub fn end_address(&self) -> u32 {
         self.mod_end
     }
@@ -36,6 +41,7 @@ pub fn module_iter(iter: TagIter) -> ModuleIter {
     ModuleIter { iter: iter }
 }
 
+/// An iterator over all module tags.
 #[derive(Clone, Debug)]
 pub struct ModuleIter<'a> {
     iter: TagIter<'a>,

src/rsdp.rs

@@ -8,6 +8,7 @@
 
 use core::str;
 
+/// This tag contains a copy of RSDP as defined per ACPI 1.0 specification. 
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)]
 pub struct RsdpV1Tag {
@@ -21,28 +22,37 @@ pub struct RsdpV1Tag {
 }
 
 impl RsdpV1Tag {
+    /// The "RSD PTR " marker singature.
+    ///
+    /// This is originally a 8-byte C string (not null terminated!) must contain "RSD PTR ".
     pub fn signature<'a>(&'a self) -> Option<&'a str> {
         str::from_utf8(&self.signature).ok()
     }
 
+    /// The value to add to all the other bytes (of the Version 1.0 table) to calculate the Checksum of the table.
+    ///
+    /// If this value added to all the others and casted to byte isn't equal to 0, the table must be ignored. 
     pub fn checksum(&self) -> u8 {
         self.checksum
     }
 
+    /// An OEM-supplied string that identifies the OEM. 
     pub fn oem_id<'a>(&'a self) -> Option<&'a str> {
         str::from_utf8(&self.oem_id).ok()
     }
 
+    /// The revision of the ACPI.
     pub fn revision(&self) -> u8 {
         self.revision
     }
 
-    /// Get the physical address of the RSDT.
+    /// 32-bit physical (I repeat: physical) address of the RSDT table.
     pub fn rsdt_address(&self) -> usize {
         self.rsdt_address as usize
     }
 }
 
+/// This tag contains a copy of RSDP as defined per ACPI 2.0 or later specification. 
 #[derive(Clone, Copy, Debug)]
 #[repr(C, packed)]
 pub struct RsdpV2Tag {
@@ -60,27 +70,38 @@ pub struct RsdpV2Tag {
 }
 
 impl RsdpV2Tag {
+    /// The "RSD PTR " marker singature.
+    ///
+    /// This is originally a 8-byte C string (not null terminated!) must contain "RSD PTR ".
     pub fn signature<'a>(&'a self) -> Option<&'a str> {
         str::from_utf8(&self.signature).ok()
     }
 
+    /// The value to add to all the other bytes (of the Version 1.0 table) to calculate the Checksum of the table.
+    ///
+    /// If this value added to all the others and casted to byte isn't equal to 0, the table must be ignored. 
     pub fn checksum(&self) -> u8 {
         self.checksum
     }
 
+    /// An OEM-supplied string that identifies the OEM. 
     pub fn oem_id<'a>(&'a self) -> Option<&'a str> {
         str::from_utf8(&self.oem_id).ok()
     }
 
+    /// The revision of the ACPI.
     pub fn revision(&self) -> u8 {
         self.revision
     }
 
-    /// Get the physical address of the XSDT. On x86, this is truncated from 64-bit to 32-bit.
+    /// Physical address of the XSDT table.
+    ///
+    /// On x86, this is truncated from 64-bit to 32-bit.
     pub fn xsdt_address(&self) -> usize {
         self.xsdt_address as usize
     }
 
+    /// This field is used to calculate the checksum of the entire table, including both checksum fields. 
     pub fn ext_checksum(&self) -> u8 {
         self.ext_checksum
     }

src/vbe_info.rs

@@ -1,32 +1,77 @@
 use core::fmt;
 
+/// This tag contains VBE metadata, VBE controller information returned by the
+/// VBE Function 00h and VBE mode information returned by the VBE Function 01h.
 #[derive(Debug, Copy, Clone)]
 #[repr(C, packed)]
 pub struct VBEInfoTag {
     typ: u32,
     length: u32,
+
+    /// Indicates current video mode in the format specified in VBE 3.0. 
     pub mode: u16,
+
+    /// Contain the segment of the table of a protected mode interface defined in VBE 2.0+.
     pub interface_segment: u16,
+
+    /// Contain the segment offset of the table of a protected mode interface defined in VBE 2.0+.
     pub interface_offset: u16,
+
+    /// Contain the segment length of the table of a protected mode interface defined in VBE 2.0+.
     pub interface_length: u16,
+
+    /// Contains VBE controller information returned by the VBE Function `00h`.
     pub control_info: VBEControlInfo,
+
+    /// Contains VBE mode information returned by the VBE Function `01h`.
     pub mode_info: VBEModeInfo
 }
 
+/// VBE controller information.
+///
+/// The capabilities of the display controller, the revision level of the
+/// VBE implementation, and vendor specific information to assist in supporting all display
+/// controllers in the field are listed here.
+///
+/// The purpose of this struct is to provide information to the kernel about the general
+/// capabilities of the installed VBE software and hardware.
 #[derive(Copy, Clone)]
 #[repr(C, packed)]
 pub struct VBEControlInfo {
+    /// VBE Signature aka "VESA".
     pub signature: [u8; 4],
+
+    /// The VBE version.
     pub version: u16,
+
+    /// A far pointer the the OEM String.
     pub oem_string_ptr: u32,
+
+    /// Capabilities of the graphics controller.
     pub capabilities: VBECapabilities,
+
+    /// Far pointer to the video mode list.
     pub mode_list_ptr: u32,
-    pub total_memory: u16, // Measured in 64kb blocks.
-    pub oem_software_revision: u16,  
+
+    /// Number of 64KiB memory blocks (Added for VBE 2.0+).
+    pub total_memory: u16,
+
+    /// VBE implementation software revision.
+    pub oem_software_revision: u16,
+
+    /// Far pointer to the vendor name string.
     pub oem_vendor_name_ptr: u32,
+
+    /// Far pointer to the product name string.
     pub oem_product_name_ptr: u32,
+
+    /// Far pointer to the product revision string.
     pub oem_product_revision_ptr: u32,
+
+    /// Reserved for VBE implementation scratch area.
     reserved: [u8; 222],
+
+    /// Data area for OEM strings.
     oem_data: [u8; 256]
 }
 
@@ -49,35 +94,91 @@ impl fmt::Debug for VBEControlInfo {
     }
 }
 
+
+/// Extended information about a specific VBE display mode from the
+/// mode list returned by `VBEControlInfo` (VBE Function `00h`).
 #[derive(Copy, Clone)]
 #[repr(C, packed)]
 pub struct VBEModeInfo {
+    /// Mode attributes.
     pub mode_attributes: VBEModeAttributes,
+
+    /// Window A attributes.
     pub window_a_attributes: VBEWindowAttributes,
+
+    /// Window B attributes.
     pub window_b_attributes: VBEWindowAttributes,
-    pub window_granularity: u16, // Measured in kilobytes.
+
+    /// Window granularity (Measured in Kilobytes.)
+    pub window_granularity: u16,
+
+    /// Window size.
     pub window_size: u16,
+
+    /// Window A start segment.
     pub window_a_segment: u16,
+
+    /// Window B start segment.
     pub window_b_segment: u16,
+
+    /// Real mode pointer to window function.
     pub window_function_ptr: u32,
+
+    /// Bytes per scan line
     pub pitch: u16,
+
+    /// Horizontal and vertical resolution in pixels or characters.
     pub resolution: (u16, u16),
+
+    /// Character cell width and height in pixels.
     pub character_size: (u8, u8),
+
+    /// Number of memory planes.
     pub number_of_planes: u8,
+
+    /// Bits per pixel
     pub bpp: u8,
+
+    /// Number of banks
     pub number_of_banks: u8,
+
+    /// Memory model type
     pub memory_model: VBEMemoryModel,
-    pub bank_size: u8, // Measured in kilobytes.
+
+    /// Bank size (Measured in Kilobytes.)
+    pub bank_size: u8,
+
+    /// Number of images.
     pub number_of_image_pages: u8,
+
+    /// Reserved for page function.
     reserved0: u8,
+
+    /// Red colour field.
     pub red_field: VBEField,
+
+    /// Green colour field.
     pub green_field: VBEField,
+
+    /// Blue colour field.
     pub blue_field: VBEField,
+
+    /// Reserved colour field.
     pub reserved_field: VBEField,
+
+    /// Direct colour mode attributes.
     pub direct_color_attributes: VBEDirectColorAttributes,
+
+    /// Physical address for flat memory frame buffer
     pub framebuffer_base_ptr: u32,
+
+    /// This should be a reserved field???
     pub offscreen_memory_offset: u32,
+
+    /// This should be a reserved field???
     pub offscreen_memory_size: u16,
+
+    /// Remainder of mode info block
     reserved1: [u8; 206]
 }
 
@@ -115,50 +216,103 @@ impl fmt::Debug for VBEModeInfo {
     }
 }
 
+/// A VBE colour field.
+///
+/// Descirbes the size and position of some colour capability.
 #[derive(Debug, PartialEq, Copy, Clone)]
 #[repr(C, packed)]
 pub struct VBEField {
+    /// The size, in bits, of the color components of a direct color pixel.
     pub size: u8,
+
+    /// define the bit position within the direct color pixel or YUV pixel of
+    /// the least significant bit of the respective color component.
     pub position: u8
 }
 
 bitflags! {
+    /// The Capabilities field indicates the support of specific features in the graphics environment.
     pub struct VBECapabilities: u32 {
+        /// Can the DAC be switched between 6 and 8 bit modes.
         const SWITCHABLE_DAC = 0x1;     // The DAC can be switched between 6 and 8-bit modes.
+
+        /// Is the controller VGA compatible.
         const NOT_VGA_COMPATIBLE = 0x2; // The controller can be switched into VGA modes.
+
+        /// The operating behaviour of the RAMDAC
         const RAMDAC_FIX = 0x4;         // When writing lots of information to the palette, the blank bit should be used.
     }
 }
 
 bitflags! {
+    /// A Mode attributes bitfield.
     pub struct VBEModeAttributes: u16 {
+        /// Mode supported by hardware configuration.
         const SUPPORTED = 0x1;           // This mode is supported by the hardware.
+
+        /// TTY Output functions supported by BIOS
         const TTY_SUPPORTED = 0x4;       // TTY output is supported.
+
+        /// Color support.
         const COLOR = 0x8;
+
+        /// Mode type (text or graphics).
         const GRAPHICS = 0x10;
+
+        /// VGA compatibility.
         const NOT_VGA_COMPATIBLE = 0x20;
-        const NO_VGA_WINDOW = 0x40;      // If this is set, the window A and B fields of VBEModeInfo are invalid.
-        const LINEAR_FRAMEBUFFER = 0x80; // A linear framebuffer is available for this mode.
+
+        /// VGA Window compatibility.
+        ///
+        /// If this is set, the window A and B fields of VBEModeInfo are invalid. 
+        const NO_VGA_WINDOW = 0x40;
+
+        /// Linear framebugger availability.
+        ///
+        /// Set if a linear framebuffer is available for this mode.
+        const LINEAR_FRAMEBUFFER = 0x80;
     }
 }
 
 bitflags! {
+    /// The WindowAttributes describe the characteristics of the CPU windowing
+    /// scheme such as whether the windows exist and are read/writeable, as follows:
     pub struct VBEWindowAttributes: u8 {
+        /// Relocatable window(s) supported?
         const RELOCATABLE = 0x1;
+
+        /// Window is readable?
         const READABLE = 0x2;
+
+        /// Window is writeable?
         const WRITEABLE = 0x4;
     }
 }
 
 bitflags! {
+
+    /// The DirectColorModeInfo field describes important characteristics of direct color modes.
+    ///
+    /// Bit D0 specifies whether the color ramp of the DAC is fixed or
+    /// programmable. If the color ramp is fixed, then it can not be changed.
+    /// If the color ramp is programmable, it is assumed that the red, green,
+    /// and blue lookup tables can be loaded by using VBE Function 09h
+    /// (it is assumed all color ramp data is 8 bits per primary).
+    /// Bit D1 specifies whether the bits in the Rsvd field of the direct color
+    /// pixel can be used by the application or are reserved, and thus unusable.
     pub struct VBEDirectColorAttributes: u8 {
-        const PROGRAMMABLE = 0x1;       // The color ramp of the DAC is programmable.
-        const RESERVED_USABLE = 0x2;    // The bits of the 'reserved' field are usable by the application.
+        /// Color ramp is fixed/programmable
+        const PROGRAMMABLE = 0x1;
+
+        /// Bits in Rsvd field are usable/reserved
+        const RESERVED_USABLE = 0x2;
     }
 }
 
+/// The MemoryModel field specifies the general type of memory organization used in modes.
 #[derive(Debug, PartialEq, Copy, Clone)]
 #[repr(u8)]
+#[allow(missing_docs)]
 pub enum VBEMemoryModel {
     Text = 0x00,
     CGAGraphics = 0x01,
@@ -168,4 +322,4 @@ pub enum VBEMemoryModel {
     Unchained = 0x05,
     DirectColor = 0x06,
     YUV = 0x07
-}
+}