Use intra-doc links, capitalize GBM wording

README.md

@@ -19,7 +19,7 @@ Add to your Cargo.toml
 
 ## Example
 
-```rust,no_run
+```rust
 extern crate drm;
 extern crate gbm;
 
@@ -29,7 +29,7 @@ use gbm::{Device, Format, BufferObjectFlags};
 // ... init your drm device ...
 let drm = init_drm_device();
 
-// init a gbm device
+// init a GBM device
 let gbm = Device::new(drm).unwrap();
 
 // create a buffer

src/buffer_object.rs

@@ -12,7 +12,7 @@ use std::os::unix::io::{AsRawFd, RawFd};
 use std::ptr;
 use std::slice;
 
-/// A gbm buffer object
+/// A GBM buffer object
 pub struct BufferObject<T: 'static> {
     pub(crate) ffi: Ptr<ffi::gbm_bo>,
     pub(crate) _device: WeakPtr<::ffi::gbm_device>,
@@ -23,9 +23,9 @@ unsafe impl Send for Ptr<::ffi::gbm_bo> {}
 
 bitflags! {
     /// Flags to indicate the intended use for the buffer - these are passed into
-    /// `Device::create_buffer_object`.
+    /// [`Device::create_buffer_object()`].
     ///
-    /// Use `Device::is_format_supported` to check if the combination of format
+    /// Use [`Device::is_format_supported()`] to check if the combination of format
     /// and use flags are supported
     pub struct BufferObjectFlags: u32 {
         /// Buffer is going to be presented to the screen using an API such as KMS
@@ -38,8 +38,8 @@ bitflags! {
         /// Buffer is to be used for rendering - for example it is going to be used
         /// as the storage for a color buffer
         const RENDERING    = ::ffi::gbm_bo_flags::GBM_BO_USE_RENDERING as u32;
-        /// Buffer can be used for gbm_bo_write.  This is guaranteed to work
-        /// with `BufferObjectFlags::Cursor`, but may not work for other combinations.
+        /// Buffer can be used for [`BufferObject::write()`].  This is guaranteed to work
+        /// with [`Self::CURSOR`], but may not work for other combinations.
         const WRITE        = ::ffi::gbm_bo_flags::GBM_BO_USE_WRITE as u32;
         /// Buffer is linear, i.e. not tiled.
         const LINEAR       = ::ffi::gbm_bo_flags::GBM_BO_USE_LINEAR as u32;
@@ -195,7 +195,7 @@ impl<T: 'static> BufferObject<T> {
             Err(DeviceDestroyedError)
         }
     }
-    
+
     /// Get the bits per pixel of the buffer object
     pub fn bpp(&self) -> Result<u32, DeviceDestroyedError> {
         let device = self._device.upgrade();
@@ -205,7 +205,7 @@ impl<T: 'static> BufferObject<T> {
             Err(DeviceDestroyedError)
         }
     }
-    
+
     /// Get the offset for a plane of the buffer object
     pub fn offset(&self, plane: i32) -> Result<u32, DeviceDestroyedError> {
         let device = self._device.upgrade();
@@ -215,7 +215,7 @@ impl<T: 'static> BufferObject<T> {
             Err(DeviceDestroyedError)
         }
     }
-    
+
     /// Get the plane count of the buffer object
     pub fn plane_count(&self) -> Result<u32, DeviceDestroyedError> {
         let device = self._device.upgrade();
@@ -225,7 +225,7 @@ impl<T: 'static> BufferObject<T> {
             Err(DeviceDestroyedError)
         }
     }
-    
+
     /// Get the modifier of the buffer object
     pub fn modifier(&self) -> Result<Modifier, DeviceDestroyedError> {
         let device = self._device.upgrade();
@@ -239,7 +239,7 @@ impl<T: 'static> BufferObject<T> {
     /// Get a DMA-BUF file descriptor for the buffer object
     ///
     /// This function creates a DMA-BUF (also known as PRIME) file descriptor
-    /// handle for the buffer object.  Each call to gbm_bo_get_fd() returns a new
+    /// handle for the buffer object.  Each call to [`Self::fd()`] returns a new
     /// file descriptor and the caller is responsible for closing the file
     /// descriptor.
     pub fn fd(&self) -> Result<RawFd, DeviceDestroyedError> {
@@ -253,7 +253,7 @@ impl<T: 'static> BufferObject<T> {
 
     /// Get the handle of the buffer object
     ///
-    /// This is stored in the platform generic union `BufferObjectHandle` type. However
+    /// This is stored in the platform generic union [`BufferObjectHandle`] type.  However
     /// the format of this handle is platform specific.
     pub fn handle(&self) -> Result<BufferObjectHandle, DeviceDestroyedError> {
         let device = self._device.upgrade();
@@ -266,7 +266,7 @@ impl<T: 'static> BufferObject<T> {
 
     /// Get the handle of a plane of the buffer object
     ///
-    /// This is stored in the platform generic union `BufferObjectHandle` type. However
+    /// This is stored in the platform generic union [`BufferObjectHandle`] type.  However
     /// the format of this handle is platform specific.
     pub fn handle_for_plane(&self, plane: i32) -> Result<BufferObjectHandle, DeviceDestroyedError> {
         let device = self._device.upgrade();
@@ -277,9 +277,9 @@ impl<T: 'static> BufferObject<T> {
         }
     }
 
-    /// Map a region of a gbm buffer object for cpu access
+    /// Map a region of a GBM buffer object for cpu access
     ///
-    /// This function maps a region of a gbm bo for cpu read access.
+    /// This function maps a region of a GBM bo for cpu read access.
     pub fn map<'a, D, F, S>(&'a self, device: &Device<D>, x: u32, y: u32, width: u32, height: u32, f: F) -> Result<IoResult<S>, WrongDeviceError>
         where
             D: AsRawFd + 'static,
@@ -328,9 +328,9 @@ impl<T: 'static> BufferObject<T> {
         }
     }
 
-    /// Map a region of a gbm buffer object for cpu access
+    /// Map a region of a GBM buffer object for cpu access
     ///
-    /// This function maps a region of a gbm bo for cpu read/write access.
+    /// This function maps a region of a GBM bo for cpu read/write access.
     pub fn map_mut<'a, D, F, S>(
         &'a mut self,
         device: &Device<D>,
@@ -389,7 +389,7 @@ impl<T: 'static> BufferObject<T> {
 
     ///  Write data into the buffer object
     ///
-    /// If the buffer object was created with the `BufferObjectFlags::Write` flag,
+    /// If the buffer object was created with the [`BufferObjectFlags::WRITE`] flag,
     /// this function can be used to write data into the buffer object.  The
     /// data is copied directly into the object and it's the responsibility
     /// of the caller to make sure the data represents valid pixel data,
@@ -573,7 +573,7 @@ impl<T: 'static> DrmPlanarBuffer for BufferObject<T> {
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-/// Thrown when the gbm device does not belong to the buffer object
+/// Thrown when the GBM device does not belong to the buffer object
 pub struct WrongDeviceError;
 
 impl fmt::Display for WrongDeviceError {

src/device.rs

@@ -67,10 +67,10 @@ impl Device<FdWrapper> {
     /// Open a GBM device from a given unix file descriptor.
     ///
     /// The file descriptor passed in is used by the backend to communicate with
-    /// platform for allocating the memory. For allocations using DRI this would be
-    /// the file descriptor returned when opening a device such as /dev/dri/card0.
+    /// platform for allocating the memory.  For allocations using DRI this would be
+    /// the file descriptor returned when opening a device such as `/dev/dri/card0`.
     ///
-    /// # Unsafety
+    /// # Safety
     ///
     /// The lifetime of the resulting device depends on the ownership of the file descriptor.
     /// Closing the file descriptor before dropping the Device will lead to undefined behavior.
@@ -92,15 +92,15 @@ impl<T: AsRawFd + 'static> Device<T> {
     /// Open a GBM device from a given open DRM device.
     ///
     /// The underlying file descriptor passed in is used by the backend to communicate with
-    /// platform for allocating the memory. For allocations using DRI this would be
-    /// the file descriptor returned when opening a device such as /dev/dri/card0.
+    /// platform for allocating the memory.  For allocations using DRI this would be
+    /// the file descriptor returned when opening a device such as `/dev/dri/card0`.
     pub fn new(fd: T) -> IoResult<Device<T>> {
         let ptr = unsafe { ::ffi::gbm_create_device(fd.as_raw_fd()) };
         if ptr.is_null() {
             Err(IoError::last_os_error())
         } else {
             Ok(Device {
-                fd: fd,
+                fd,
                 ffi: Ptr::<::ffi::gbm_device>::new(ptr, |ptr| unsafe { ::ffi::gbm_device_destroy(ptr) }),
             })
         }
@@ -199,7 +199,7 @@ impl<T: AsRawFd + 'static> Device<T> {
             Ok(unsafe { BufferObject::new(ptr, self.ffi.downgrade()) })
         }
     }
-    
+
     ///  Allocate a buffer object for the given dimensions with explicit modifiers
     pub fn create_buffer_object_with_modifiers<U: 'static>(
         &self,
@@ -226,13 +226,13 @@ impl<T: AsRawFd + 'static> Device<T> {
         }
     }
 
-    /// Create a gbm buffer object from a wayland buffer
+    /// Create a GBM buffer object from a wayland buffer
     ///
-    /// This function imports a foreign `WlBuffer` object and creates a new gbm
+    /// This function imports a foreign [`WlBuffer`] object and creates a new GBM
     /// buffer object for it.
-    /// This enabled using the foreign object with a display API such as KMS.
+    /// This enables using the foreign object with a display API such as KMS.
     ///
-    /// The gbm bo shares the underlying pixels but its life-time is
+    /// The GBM bo shares the underlying pixels but its life-time is
     /// independent of the foreign object.
     #[cfg(feature = "import-wayland")]
     pub fn import_buffer_object_from_wayland<U: 'static>(
@@ -255,18 +255,18 @@ impl<T: AsRawFd + 'static> Device<T> {
         }
     }
 
-    /// Create a gbm buffer object from an egl buffer
+    /// Create a GBM buffer object from an egl buffer
     ///
-    /// This function imports a foreign `EGLImage` object and creates a new gbm
+    /// This function imports a foreign [`EGLImage`] object and creates a new GBM
     /// buffer object for it.
-    /// This enabled using the foreign object with a display API such as KMS.
+    /// This enables using the foreign object with a display API such as KMS.
     ///
-    /// The gbm bo shares the underlying pixels but its life-time is
+    /// The GBM bo shares the underlying pixels but its life-time is
     /// independent of the foreign object.
     ///
-    /// ## Unsafety
+    /// # Safety
     ///
-    /// The given EGLImage is a raw pointer. Passing null or an invalid EGLImage will
+    /// The given [`EGLImage`] is a raw pointer.  Passing null or an invalid [`EGLImage`] will
     /// cause undefined behavior.
     #[cfg(feature = "import-egl")]
     pub unsafe fn import_buffer_object_from_egl<U: 'static>(
@@ -288,13 +288,13 @@ impl<T: AsRawFd + 'static> Device<T> {
         }
     }
 
-    /// Create a gbm buffer object from an dma buffer
+    /// Create a GBM buffer object from a dma buffer
     ///
     /// This function imports a foreign dma buffer from an open file descriptor
-    /// and creates a new gbm buffer object for it.
-    /// This enabled using the foreign object with a display API such as KMS.
+    /// and creates a new GBM buffer object for it.
+    /// This enables using the foreign object with a display API such as KMS.
     ///
-    /// The gbm bo shares the underlying pixels but its life-time is
+    /// The GBM bo shares the underlying pixels but its life-time is
     /// independent of the foreign object.
     pub fn import_buffer_object_from_dma_buf<U: 'static>(
         &self,
@@ -327,14 +327,14 @@ impl<T: AsRawFd + 'static> Device<T> {
             Ok(unsafe { BufferObject::new(ptr, self.ffi.downgrade()) })
         }
     }
-    
-    /// Create a gbm buffer object from an dma buffer with explicit modifiers
+
+    /// Create a GBM buffer object from a dma buffer with explicit modifiers
     ///
     /// This function imports a foreign dma buffer from an open file descriptor
-    /// and creates a new gbm buffer object for it.
-    /// This enabled using the foreign object with a display API such as KMS.
+    /// and creates a new GBM buffer object for it.
+    /// This enables using the foreign object with a display API such as KMS.
     ///
-    /// The gbm bo shares the underlying pixels but its life-time is
+    /// The GBM bo shares the underlying pixels but its life-time is
     /// independent of the foreign object.
     pub fn import_buffer_object_from_dma_buf_with_modifiers<U: 'static>(
         &self,
@@ -382,12 +382,12 @@ impl<T: DrmDevice + AsRawFd + 'static> DrmDevice for Device<T> {}
 impl<T: DrmControlDevice + AsRawFd + 'static> DrmControlDevice for Device<T> {}
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-/// Thrown when the underlying gbm device was already destroyed
+/// Thrown when the underlying GBM device was already destroyed
 pub struct DeviceDestroyedError;
 
 impl fmt::Display for DeviceDestroyedError {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(f, "The underlying gbm device was already destroyed")
+        write!(f, "The underlying GBM device was already destroyed")
     }
 }
 

src/lib.rs

@@ -47,7 +47,7 @@
 //! // ... init your drm device ...
 //! let drm = init_drm_device();
 //!
-//! // init a gbm device
+//! // init a GBM device
 //! let gbm = Device::new(drm).unwrap();
 //!
 //! // create a 4x4 buffer
@@ -110,7 +110,7 @@ pub use self::surface::*;
 
 use std::sync::{Arc, Weak};
 
-/// Trait for types that allow to optain the underlying raw libinput pointer.
+/// Trait for types that allow to obtain the underlying raw libinput pointer.
 pub trait AsRaw<T> {
     /// Receive a raw pointer representing this type.
     fn as_raw(&self) -> *const T;

src/surface.rs

@@ -3,7 +3,7 @@ use std::error;
 use std::fmt;
 use std::marker::PhantomData;
 
-/// A gbm rendering surface
+/// A GBM rendering surface
 pub struct Surface<T: 'static> {
     ffi: Ptr<::ffi::gbm_surface>,
     _device: WeakPtr<::ffi::gbm_device>,
@@ -46,9 +46,9 @@ impl<T: 'static> Surface<T> {
     ///  Return whether or not a surface has free (non-locked) buffers
     ///
     /// Before starting a new frame, the surface must have a buffer
-    /// available for rendering.  Initially, a gbm surface will have a free
+    /// available for rendering.  Initially, a GBM surface will have a free
     /// buffer, but after one or more buffers
-    /// [have been locked](#method.lock_front_buffer),
+    /// [have been locked](Self::lock_front_buffer()),
     /// the application must check for a free buffer before rendering.
     pub fn has_free_buffers(&self) -> bool {
         let device = self._device.upgrade();
@@ -62,12 +62,13 @@ impl<T: 'static> Surface<T> {
     /// Lock the surface's current front buffer
     ///
     /// Locks rendering to the surface's current front buffer and returns
-    /// a handle to the underlying `BufferObject`
+    /// a handle to the underlying [`BufferObject`].
     ///
-    /// If an error occurs a `FrontBufferError` is returned.
+    /// If an error occurs a [`FrontBufferError`] is returned.
     ///
-    /// **Unsafety**: This function must be called exactly once after calling
-    /// `eglSwapBuffers`.  Calling it before any `eglSwapBuffer` has happened
+    /// # Safety
+    /// This function must be called exactly once after calling
+    /// `eglSwapBuffers`.  Calling it before any `eglSwapBuffers` has happened
     /// on the surface or two or more times after `eglSwapBuffers` is an
     /// error and may cause undefined behavior.
     pub unsafe fn lock_front_buffer(&self) -> Result<BufferObject<T>, FrontBufferError> {