Merge pull request #62 from mental32/mental32-docs

Add some basic 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
+    ///
+    /// ```ignore
+    /// if let Some(tag) = boot_info.boot_loader_name_tag() {
+    ///     let name = tag.name();
+    ///     assert_eq!("GRUB 2.02~beta3-5", 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
+    ///
+    /// ```ignore
+    /// if let Some(tag) = boot_info.command_line_tag() {
+    ///     let command_line = tag.command_line();
+    ///     assert_eq!("/bootarg", 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
+    ///
+    /// ```ignore
+    /// 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.
     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()
     }
 
+    /// Get the section's size in bytes.
     pub fn size(&self) -> u64 {
         self.get().size()
     }
 
+    /// Get the section's 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 section's 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,74 @@ 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 linker 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 dynamic linking tables.
     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
+    /// `ProgramSection`. 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 dynamic loader symbol table.
     DynamicLoaderSymbolTable = 11,
+
+    /// Values in this inclusive range (`[0x6000_0000, 0x6FFF_FFFF)`) are
+    /// reserved for environment-specific semantics.
     EnvironmentSpecific = 0x6000_0000,
+
+    /// Values in this inclusive range (`[0x7000_0000, 0x7FFF_FFFF)`) 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

@@ -1,42 +1,81 @@
-use header::Tag;
 use ::Reader;
 use core::slice;
+use header::Tag;
 
+/// 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,
+
+    /// Contains framebuffer width in pixels.
     pub width: u32,
+
+    /// Contains framebuffer height in pixels.
     pub height: u32,
+
+    /// Contains number of bits per pixel.
     pub bpp: u8,
-    pub buffer_type: FramebufferType<'a>
+
+    /// 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 {
-        palette: &'a [FramebufferColor]
+        #[allow(missing_docs)]
+        palette: &'a [FramebufferColor],
     },
+
+    /// Direct RGB color.
+    #[allow(missing_docs)]
     RGB {
         red: FramebufferField,
         green: FramebufferField,
-        blue: FramebufferField
+        blue: FramebufferField,
     },
-    Text
+
+    /// 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,
-    pub size: 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 Red component of the color.
     pub red: u8,
+
+    /// The Green component of the color.
     pub green: u8,
-    pub blue: u8
+
+    /// The Blue component of the color.
+    pub blue: u8,
 }
 
 pub fn framebuffer_tag<'a>(tag: &'a Tag) -> FramebufferTag<'a> {
@@ -51,28 +90,40 @@ pub fn framebuffer_tag<'a>(tag: &'a Tag) -> FramebufferTag<'a> {
     reader.skip(2); // In the multiboot spec, it has this listed as a u8 _NOT_ a u16.
                     // Reading the GRUB2 source code reveals it is in fact a u16.
     let buffer_type = match type_no {
-        0 =>  {
+        0 => {
             let num_colors = reader.read_u32();
             let palette = unsafe {
-                slice::from_raw_parts(reader.current_address() as *const FramebufferColor, num_colors as usize)
+                slice::from_raw_parts(
+                    reader.current_address() as *const FramebufferColor,
+                    num_colors as usize,
+                )
             } as &'static [FramebufferColor];
             FramebufferType::Indexed { palette }
-        },
+        }
         1 => {
-            let red_pos = reader.read_u8();     // These refer to the bit positions of the LSB of each field
-            let red_mask = reader.read_u8();    // And then the length of the field from LSB to MSB
-            let green_pos = reader.read_u8();   
-            let green_mask = reader.read_u8();  
+            let red_pos = reader.read_u8(); // These refer to the bit positions of the LSB of each field
+            let red_mask = reader.read_u8(); // And then the length of the field from LSB to MSB
+            let green_pos = reader.read_u8();
+            let green_mask = reader.read_u8();
             let blue_pos = reader.read_u8();
             let blue_mask = reader.read_u8();
             FramebufferType::RGB {
-                red: FramebufferField { position: red_pos, size: red_mask },
-                green: FramebufferField { position: green_pos, size: green_mask },
-                blue: FramebufferField { position: blue_pos, size: blue_mask }
+                red: FramebufferField {
+                    position: red_pos,
+                    size: red_mask,
+                },
+                green: FramebufferField {
+                    position: green_pos,
+                    size: green_mask,
+                },
+                blue: FramebufferField {
+                    position: blue_pos,
+                    size: blue_mask,
+                },
             }
-        },
+        }
         2 => FramebufferType::Text,
-        _ => panic!("Unknown framebuffer type: {}", type_no)
+        _ => panic!("Unknown framebuffer type: {}", type_no),
     };
 
     FramebufferTag {
@@ -81,6 +132,6 @@ pub fn framebuffer_tag<'a>(tag: &'a Tag) -> FramebufferTag<'a> {
         width,
         height,
         bpp,
-        buffer_type
+        buffer_type,
     }
 }

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 (The EFI boot
+/// services tag may exist in the Multiboot2 boot 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 iterator 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!) that 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.
+    /// The 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!) that 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,86 @@
 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+.
+    ///
+    /// If the information for a protected mode interface is not available
+    /// this field is set to zero.
     pub interface_segment: u16,
+
+    /// Contain the segment offset of the table of a protected mode interface defined in VBE 2.0+.
+    ///
+    /// If the information for a protected mode interface is not available
+    /// this field is set to zero.
     pub interface_offset: u16,
+
+    /// Contain the segment length of the table of a protected mode interface defined in VBE 2.0+.
+    ///
+    /// If the information for a protected mode interface is not available
+    /// this field is set to zero.
     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 +103,99 @@ 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,
+
+    /// A pointer to the start of off screen memory.
+    ///
+    /// # Deprecated
+    ///
+    /// In VBE3.0 and above these fields are reserved and unused.
     pub offscreen_memory_offset: u32,
+
+    /// The amount of off screen memory in 1k units.
+    ///
+    /// # Deprecated
+    ///
+    /// In VBE3.0 and above these fields are reserved and unused.
     pub offscreen_memory_size: u16,
+
+    /// Remainder of mode info block
     reserved1: [u8; 206]
 }
 
@@ -115,50 +233,105 @@ 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 {
-        const SWITCHABLE_DAC = 0x1;     // The DAC can be switched between 6 and 8-bit modes.
-        const NOT_VGA_COMPATIBLE = 0x2; // The controller can be switched into VGA modes.
-        const RAMDAC_FIX = 0x4;         // When writing lots of information to the palette, the blank bit should be used.
+        /// Can the DAC be switched between 6 and 8 bit modes.
+        const SWITCHABLE_DAC = 0x1;
+
+        /// Is the controller VGA compatible.
+        const NOT_VGA_COMPATIBLE = 0x2;
+
+        /// The operating behaviour of the RAMDAC.
+        ///
+        /// When writing lots of information to the RAMDAC, use the blank bit in Function `09h`.
+        const RAMDAC_FIX = 0x4;
     }
 }
 
 bitflags! {
+    /// A Mode attributes bitfield.
     pub struct VBEModeAttributes: u16 {
-        const SUPPORTED = 0x1;           // This mode is supported by the hardware.
-        const TTY_SUPPORTED = 0x4;       // TTY output is supported.
+        /// Mode supported by hardware configuration.
+        const SUPPORTED = 0x1;
+
+        /// TTY Output functions supported by BIOS
+        const TTY_SUPPORTED = 0x4;
+
+        /// 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 framebuffer 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 when cleared and programmable when set.
+        const PROGRAMMABLE = 0x1;
+
+        /// Bits in Rsvd field when cleared are reserved and usable when set.
+        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 +341,4 @@ pub enum VBEMemoryModel {
     Unchained = 0x05,
     DirectColor = 0x06,
     YUV = 0x07
-}
+}