Documented code and added doxygen support.

.gitignore

@@ -36,3 +36,4 @@
 CMakeFiles/
 build/
 packet_hacker-cppcheck-build-dir/
+docs/html/

CMakeLists.txt

@@ -18,6 +18,25 @@ if (BUILD_SANDBOX)
     add_subdirectory(sandbox)
 endif()
 
+option(BUILD_DOC "Build documentation" ON)
+
+find_package(Doxygen)
+if (DOXYGEN_FOUND)
+    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile)
+    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+    message("Doxygen build started")
+
+    add_custom_target( doc_doxygen ALL
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM )
+else (DOXYGEN_FOUND)
+  message("Doxygen need to be installed to generate the doxygen documentation")
+endif (DOXYGEN_FOUND)
+
 # find_package(wxWidgets COMPONENTS core base propgrid aui REQUIRED)
 # include(${wxWidgets_USE_FILE})
 

include/packethacker/arp_table.h

@@ -8,25 +8,86 @@
 
 namespace PacketHacker {
 
+/**
+ * \brief Struct representation of an ARP entry on an local ARP table.
+ * 
+ * The arp table maps hardware addresses to there IP address so
+ * that ethernet frames can be created.
+ */
 struct ArpEntry
 {
-  HardwareAddress hwAddress;
-  IPv4Address ipAddress;
-  uint32_t ifIndex;
+  HardwareAddress hwAddress; /**< Hardware address of the entry. */
+  IPv4Address ipAddress; /**< IPv4 address of the entry. */
+  uint32_t ifIndex; /**< Interface index that the entry applies to. */
 };
 
+/**
+ * \brief Class representation of the ARP table of the local machine.
+ * 
+ * This class allows for manipulation of the ARP table on the local
+ * machine. Sufficient priviledges are needed for flushTable(),
+ * addEntry(), and deleteEntry().
+ * 
+ * This class should not and cannot be initialized in your code. There
+ * should only ever be one instance.
+ * 
+ * To access the ARP table call:
+ *   - ArpTable table = ArpTable::instance();
+ * 
+ */
 class ArpTable
 {
 public:
+  /**
+   * \brief Retrieves the ARP table from the local machine
+   * and stores it in a vector.
+   */
   void refreshTable();
+
+  /**
+   * \brief Removes all ARP entries from a given interface.
+   * @param ifIndex index of interface to flush
+   */
   void flushTable(uint32_t ifIndex);
 
+  /**
+   * \brief Adds an entry to the ARP table.
+   * 
+   * \warning This function requires sufficient priviledges when executed.
+   * @param ipAddress IP address of entry
+   * @param hwAddress hardware address of entry
+   * @param ifIndex index of interface to add entry to
+   */
   void addEntry(const IPv4Address &ipAddress, const HardwareAddress &hwAddress, uint32_t ifIndex);
+
+  /**
+   * \brief Deletes an entry from the ARP table.
+   * Does not need the hardware address to be defined as the
+   * table can be looked up by just the IP address.
+   * 
+   * \warning This function requires sufficient priviledges when executed.
+   * @param ipAddress IP address of entry
+   * @param ifIndex index of interface to add entry to
+   */
   void deleteEntry(const IPv4Address &ipAddress, uint32_t ifIndex);
+
+  /**
+   * \brief Retrieves an entry on the ARP table given an IP address.
+   * @param ipAddress IP address of entry to look up
+   * @return requested entry or nullptr if not found
+   */
   ArpEntry *getEntry(const IPv4Address &ipAddress);
 
+  /**
+   * \brief Returns the entries that have been retrieved from the local machine.
+   * @return std::vector of ARP entries
+   */
   std::vector<ArpEntry> &entries() { return m_entries; }
 
+  /**
+   * \brief Returns the static instance of this class.
+   * @return ArpTable instance
+   */
   static ArpTable &instance()
   {
     static ArpTable instance;

include/packethacker/constants.h

@@ -1,13 +1,27 @@
 #pragma once
 
 namespace PacketHacker {
+
+/**
+ * \brief List of constants
+ */
 namespace Constants {
 
+  /**
+   * \brief Ethernet constants.
+   * 
+   * List of acceptable ethertypes.
+   */
   enum Ethernet {
     TYPE_IPv4 = 0x0800,
     TYPE_ARP = 0x0806,
   };
 
+  /**
+   * \brief IP constants.
+   * 
+   * List of protocols supported by IP.
+   */
   enum IP {
     TYPE_ICMP = 1,
     TYPE_IGMP = 2,

include/packethacker/hardware_address.h

@@ -10,36 +10,122 @@ namespace Utils {
   void stringToHardwareAddress(const std::string &hwAddress, uint8_t *buf, size_t bufSize);
 }// namespace Utils
 
+/**
+ * \brief Class container for hardware addresses.
+ * 
+ * This class encapsulates hardware address functionality,
+ * mostly for the ease of converting multiple types to a
+ * byte array. 
+ * 
+ * There are several ways to instantiate a hardware address:\n
+ *   - Integer parts: HardwareAddress hw(0xff, 0xff, 0xff, 0xff, 0xff, 0xff);\n
+ *   - std::array: HardwareAddress hw = {0xff, 0xff, 0xff, 0xff, 0xff, 0xff};\n
+ *   - From a string: HardwareAddress hw = "ff:ff:ff:ff:ff:ff";
+ * 
+ * You can also instantiate a hardware address from a c byte array.
+ * 
+ * When writing to a buffer use the ptr() function to access the pointer
+ * to the first element.
+ */
 class HardwareAddress
 {
 public:
+  /**
+   * \brief Default constructor, initializes array with zeroes.
+   */
   HardwareAddress();
+
+  /**
+   * \brief Initializes from integer parts.
+   * @param b1 first byte
+   * @param b2 second byte
+   * @param b3 third byte
+   * @param b4 fourth byte
+   * @param b5 fifth byte
+   * @param b6 sixth byte
+   */
   HardwareAddress(const uint8_t b1,
     const uint8_t b2,
     const uint8_t b3,
     const uint8_t b4,
     const uint8_t b5,
     const uint8_t b6);
+
+  /**
+   * \brief Initializes from std::array.
+   * @param data std::array containing hardware address data
+   */
   HardwareAddress(const std::array<uint8_t, PHYSICAL_ADDR_LEN> &data);
+
+  /**
+   * \brief Initializes from std::string.
+   * 
+   * Must follow the format hx:hx:hx:hx:hx:hx
+   * @param address std::string hardware address
+   */
   HardwareAddress(const std::string &address);
+
+  /**
+   * \brief Initializes from a c byte array.
+   * 
+   * The size of the array must be PHYSICAL_ADDR_LEN.
+   * @param data array of data containing hardware address
+   */
   explicit HardwareAddress(const uint8_t *data);
 
+  /**
+   * \brief Returns address of first byte.
+   * 
+   * Useful for when writing the hardware address to buffer.
+   * @return pointer to first byte of hardware address
+   */
   const uint8_t *ptr() const { return m_data.data(); }
+
+  /**
+   * \brief Returns the array containing bytes for hardware address.
+   * @return std::array of data
+   */
   const std::array<uint8_t, PHYSICAL_ADDR_LEN> &data() const { return m_data; }
+
+  /**
+   * \brief Returns string representation of hardware address.
+   * @return string representation of hardware address
+   */
   std::string toString() const;
 
+  /**
+   * \brief Returns whether a hardware address string is valid.
+   * 
+   * If the string does not follow the format hx:hx:hx:hx:hx:hx, or
+   * it does not have 6 bytes, then the function returns false.
+   * @return true if correct format, false otherwise
+   */
   static bool isHardwareAddressValid(const std::string &hwAddress);
 
+  /**
+   * \brief Returns boolean equivalence between two hardware addresses.
+   * @return true if addresses are equal, false otherwise 
+   */
   bool operator==(const HardwareAddress &rhs) const
   {
     return m_data == rhs.m_data;
   }
 
+  /**
+   * \brief Returns boolean negation of equality operation.
+   * @return true if addresses are not equal, false otherwise
+   */
   bool operator!=(const HardwareAddress &rhs) const
   {
     return !((*this) == rhs);
   }
 
+  /**
+   * \brief Prints the Hardware address to a std::ostream.
+   * @param output stream to print to
+   * @param hwAddress address to print
+   * @return stream that was printed to
+   */
   friend std::ostream &operator<<(std::ostream &output, const HardwareAddress &hwAddress);
 
 private:

include/packethacker/interface_table.h

@@ -9,31 +9,75 @@
 
 namespace PacketHacker {
 
+/**
+ * \brief Struct representation of an interface entry on a local interface table.
+ * 
+ * Provides information about the ip addressing of an interface
+ * as well as its name and description. Passed into a PacketStream 
+ * to send and receive packets on an interface.
+ */
 struct Interface
 {
-  uint32_t index;
-  HardwareAddress address;
-  IPv4Address unicastAddress;
-  IPv4Address anycastAddress;
-  IPv4Address multicastAddress;
-  IPv4Address dnsServerAddress;
-  IPv4Address gatewayAddress;
-  std::string name;
-  std::wstring dnsSuffix;
-  std::wstring description;
-  std::wstring friendlyName;
+  uint32_t index; /**< Integer index of the interface on the local machine. */
+  HardwareAddress address; /**< Hardware address of the interface. */
+  IPv4Address unicastAddress; /**< IPv4 address of the interface. */
+  IPv4Address anycastAddress; /**< Anycast address of the interface if it exists. */
+  IPv4Address multicastAddress; /**< Multicast address of the interface if it exists. */
+  IPv4Address dnsServerAddress; /**< DNS server address of the interface if it exists. */
+  IPv4Address gatewayAddress; /**< Gatewat address of the interface if it exists. */
+  std::string name; /**< String name of the interface. */
+  std::wstring dnsSuffix; /**< DNS suffix of the interface if it exists. */
+  std::wstring description; /**< String description of the interface. */
+  std::wstring friendlyName; /**< Easier to read name of the interface. */
 };
 
+/**
+ * \brief Class representation of the interface table on a local machine.
+ * 
+ * This allows for the access of all interfaces that are on the local
+ * machine, including virtual interfaces.
+ * 
+ * This class should not and cannot be initialized in your 
+ * code. There should only ever be one instance.
+ * 
+ * To access the interface table call:
+ *   - InterfaceTable table = InterfaceTable::instance();
+ */
 class InterfaceTable
 {
 public:
+  /**
+   * \brief Retrieves all local interfaces and adds them to a vector.
+   * 
+   * Only realistically needs to be called once, yet the functionality
+   * is here if needed.
+   */
   void refreshTable();
+
+  /**
+   * \brief Returns the best interface to send packets to a specific IP.
+   * @param address IPv4 address of the machine to be sent to
+   * @return interface pointer of the best interface or nullptr.
+   */
   Interface *bestInterface(IPv4Address &address);
 
+  /**
+   * \brief Returns the interface with the given index.
+   * @param ifIndex index of the interface to be returned
+   * @return interface of given index or nullptr if none found
+   */
   Interface *getInterface(const uint32_t ifIndex);
 
+  /**
+   * \brief Returns the vector of local interfaces retrieved.
+   * @return std::vector of interfaces
+   */
   std::vector<Interface> &interfaces() { return m_interfaces; }
 
+  /**
+   * \brief Returns the static instance of this class.
+   * @return InterfaceTable instance
+   */
   static InterfaceTable &instance()
   {
     static InterfaceTable instance;