hw: Add API documentation to the block device interface

api/hw/block_device.hpp

@@ -1,6 +1,6 @@
 // This file is a part of the IncludeOS unikernel - www.includeos.org
 //
-// Copyright 2015 Oslo and Akershus University College of Applied Sciences
+// Copyright 2015-2017 Oslo and Akershus University College of Applied Sciences
 // and Alfred Bratterud
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,71 +16,148 @@
 // limitations under the License.
 
 #pragma once
-#ifndef HW_DRIVE_HPP
-#define HW_DRIVE_HPP
+#ifndef HW_BLOCK_DEVICE_HPP
+#define HW_BLOCK_DEVICE_HPP
 
-#include <memory>
 #include <cstdint>
 #include <delegate>
+#include <memory>
 
-namespace hw
-{
-
-  /**
-   * Abstract interface for block devices of various driver types
-   **/
-  class Block_device {
-  public:
-    using block_t = uint64_t; //< Disk device block size
-    using buffer_t = std::shared_ptr<uint8_t>;
-
-    // Delegate for result of reading a disk sector
-    //using on_read_func = delegate<void(buffer_t)>;
-    using on_read_func = delegate<void(buffer_t)>;
+namespace hw {
 
-    using Device_id = int;
+/**
+ * This class is an abstract interface for block devices
+ */
+class Block_device {
+public:
+  using block_t      = uint64_t;                 //< Representation for a device's block size
+  using buffer_t     = std::shared_ptr<uint8_t>; //< Representation for a block device's buffer
+  using Device_id    = int32_t;                  //< Representation for a block device's identifier
+  using on_read_func = delegate<void(buffer_t)>; //< Delegate for result of reading from a block device
 
-    static const char* device_type()
-    { return "Block device"; }
+  /**
+   * Method to get the type of device
+   *
+   * @return The type of device as a C-String
+   */
+  static const char* device_type() noexcept
+  { return "Block device"; }
 
-    virtual std::string device_name() const = 0;
+  /**
+   * Method to get the name of the device
+   *
+   * @return The name of the device as a std::string
+   */
+  virtual std::string device_name() const = 0;
 
-    Device_id id() const { return id_; }
+  /**
+   * Method to get the device's identifier
+   *
+   * @return The device's identifier
+   */
+  Device_id id() const noexcept
+  { return id_; }
 
-    /** Human-readable name of this disk controller  */
-    virtual const char* driver_name() const noexcept = 0;
+  /**
+   * Get the human-readable name of this device's controller
+   *
+   * @return The human-readable name of this device's controller
+   */
+  virtual const char* driver_name() const noexcept = 0;
 
-    /** The size of the disk in whole sectors */
-    virtual block_t size() const noexcept = 0;
+  /**
+   * Get the size of the device as total number of blocks
+   *
+   * @return The size of the device as total number of blocks
+   */
+  virtual block_t size() const noexcept = 0;
 
-    /** Returns the optimal block size for this device */
-    virtual block_t block_size() const noexcept = 0;
+  /**
+   * Get the optimal block size for this device
+   *
+   * @return The optimal block size for this device
+   */
+  virtual block_t block_size() const noexcept = 0;
 
-    /**
-     *  Read block(s) from blk and call func with result
-     *  A null-pointer is passed to result if something bad happened
-     *  Validate using !buffer_t:
-     *  if (!buffer)
-     *     error("Device failed to read sector");
-     **/
-    virtual void read(block_t blk, on_read_func func) = 0;
-    virtual void read(block_t blk, size_t count, on_read_func) = 0;
+  /**
+   * Read a block of data asynchronously from the device
+   *
+   * @param blk
+   *   The block of data to read from the device
+   *
+   * @param reader
+   *   An operation to perform asynchronously
+   *
+   * @note A nullptr is passed to the reader if an error occurred
+   * @note Validate the reader's input
+   *
+   * @example
+   *   if (buffer == nullptr) {
+   *     error("Device failed to read sector");
+   *   }
+   */
+  virtual void read(block_t blk, on_read_func reader) = 0;
 
-    /** read synchronously the block @blk  */
-    virtual buffer_t read_sync(block_t blk) = 0;
-    virtual buffer_t read_sync(block_t blk, size_t count) = 0;
+  /**
+   * Read blocks of data asynchronously from the device
+   *
+   * @param blk
+   *   The starting block of data to read from the device
+   *
+   * @param count
+   *   The number of blocks to read from the device
+   *
+   * @param reader
+   *   An operation to perform asynchronously
+   *
+   * @note A nullptr is passed to the reader if an error occurred
+   * @note Validate the reader's input
+   *
+   * @example
+   *   if (buffer == nullptr) {
+   *     error("Device failed to read sector");
+   *   }
+   */
+  virtual void read(block_t blk, size_t count, on_read_func reader) = 0;
 
-    virtual void deactivate() = 0;
+  /**
+   * Read a block of data synchronously from the device
+   *
+   * @param blk
+   *   The block of data to read from the device
+   *
+   * @return A buffer containing the data or nullptr if an error occurred
+   */
+  virtual buffer_t read_sync(block_t blk) = 0;
 
-    virtual ~Block_device() noexcept = default;
+  /**
+   * Read blocks of data synchronously from the device
+   *
+   * @param blk
+   *   The starting block of data to read from the device
+   *
+   * @param count
+   *   The number of blocks to read from the device
+   *
+   * @return A buffer containing the data or nullptr if an error occurred
+   */
+  virtual buffer_t read_sync(block_t blk, size_t count) = 0;
 
-  protected:
-    Block_device();
+  /**
+   * Method to deactivate the block device
+   */
+  virtual void deactivate() = 0;
 
-  private:
-    int id_;
-  }; //< class Drive
+  /**
+   * Default destructor
+   */
+  virtual ~Block_device() noexcept = default;
+protected:
+  Block_device();
+private:
+  Device_id id_;
+}; //< class Block_device
 
 } //< namespace hw
 
-#endif //< HW_DRIVE_HPP
+#endif //< HW_BLOCK_DEVICE_HPP