From 9fec17d47bff65586f27616aedcce9489ca5e90f Mon Sep 17 00:00:00 2001
From: Baptiste Wicht <baptiste.wicht@gmail.com>
Date: Thu, 29 Sep 2016 09:51:46 +0200
Subject: [PATCH] Doc

---
 kernel/include/net/arp_cache.hpp | 42 ++++++++++++++++++++++++++++----
 kernel/include/net/arp_layer.hpp |  9 ++++---
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/kernel/include/net/arp_cache.hpp b/kernel/include/net/arp_cache.hpp
index 544554a5..1852828e 100644
--- a/kernel/include/net/arp_cache.hpp
+++ b/kernel/include/net/arp_cache.hpp
@@ -27,20 +27,52 @@ namespace arp {
 
 struct layer;
 
+/*!
+ * \brief An entry in the ARP cache
+ */
 struct cache_entry {
-    uint64_t mac;
-    network::ip::address ip;
+    uint64_t mac;            ///< The MAC address
+    network::ip::address ip; ///< The IP address
 
+    /*!
+     * \brief Construct a new empty cache entry
+     */
     cache_entry(){}
+
+    /*!
+     * \brief Construct a new cache entry
+     * \param mac The MAC address
+     * \param ip The IP address
+     */
     cache_entry(uint64_t mac, network::ip::address ip) : mac(mac), ip(ip) {}
 };
 
+/*!
+ * \brief An ARP cache
+ */
 struct cache {
+    /*!
+     * \brief Construct a new cache.
+     * \param layer The ARP layer
+     * \param parent The parent layer (ethernet layer)
+     */
     cache(network::arp::layer* layer, network::ethernet::layer* parent);
 
+    /*!
+     * \brief Update the cache entry for the given MAC address
+     * \param mac The MAC address
+     * \param ip The IP address
+     */
     void update_cache(uint64_t mac, network::ip::address ip);
 
+    /*!
+     * \brief Indicates if the given MAC address is cached or not
+     */
     bool is_mac_cached(uint64_t mac) const ;
+
+    /*!
+     * \brief Indicates if the given IP address is cached or not
+     */
     bool is_ip_cached(network::ip::address ip) const ;
 
     /*!
@@ -83,10 +115,10 @@ struct cache {
 private:
     std::expected<void> arp_request(network::interface_descriptor& interface, network::ip::address ip);
 
-    network::arp::layer* arp_layer;
-    network::ethernet::layer* ethernet_layer;
+    network::arp::layer* arp_layer; ///< The ARP layer
+    network::ethernet::layer* ethernet_layer; ///< The ethernet layer
 
-    std::vector<cache_entry> mac_cache;
+    std::vector<cache_entry> mac_cache; ///< The cache of MAC addresses
 };
 
 } // end of arp namespace
diff --git a/kernel/include/net/arp_layer.hpp b/kernel/include/net/arp_layer.hpp
index e928c678..85f2b335 100644
--- a/kernel/include/net/arp_layer.hpp
+++ b/kernel/include/net/arp_layer.hpp
@@ -57,16 +57,19 @@ struct layer {
      */
     void decode(network::interface_descriptor& interface, network::packet& packet);
 
+    /*!
+     * \brief Returns a reference to the ARP cache
+     */
     network::arp::cache& get_cache();
 
     void wait_for_reply();
     void wait_for_reply(size_t ms);
 
 private:
-    network::ethernet::layer* parent;
-    network::arp::cache _cache;
+    network::ethernet::layer* parent; ///< The parent layer (ethernet)
+    network::arp::cache _cache; ///< The ARP cache
 
-    condition_variable wait_queue;
+    condition_variable wait_queue; ///< Wait queue for ARP packets
 };
 
 } // end of arp namespace