From 70a3a4cef58fee0fd62a4181b210ad633c753f28 Mon Sep 17 00:00:00 2001
From: Amelia Coutard <eliottulio.coutard@gmail.com>
Date: Sat, 4 Jun 2022 16:23:47 +0200
Subject: [PATCH] Added Doxygen comments to all of the phys_ptr class

---
 src/phys_ptr.hpp | 50 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/src/phys_ptr.hpp b/src/phys_ptr.hpp
index 256cd5d..bfae710 100644
--- a/src/phys_ptr.hpp
+++ b/src/phys_ptr.hpp
@@ -5,69 +5,119 @@
 
 namespace os {
 
+/** \brief A class that handles the translation from physical to virtual addresses.
+ *
+ * It avoids the risk of translating an address zero or two times, by storing
+ * physical addresses as a different class.
+ */
 template <typename T>
 class phys_ptr {
 public:
+	/** Constructs a phys_ptr corresponding to the given physical address.
+	 */
 	constexpr explicit phys_ptr(std::uintptr_t phys_addr): phys_addr(phys_addr) {}
+	/** Constructs a phys_ptr that doesn't correspond to any place in physical memory.
+	 * It is represented internally by ~0 instead of 0 to allow for access of physical address 0.
+	 */
 	constexpr phys_ptr(std::nullptr_t): phys_addr(~0ull) {}
 
+	/** Access the T at the physical address of the ith element of a T array starting at this physical address.
+	 */
 	T& operator[](std::size_t i) const {
 		return get_virt_addr()[i];
 	}
+	/** Access the T at this physical address.
+	 */
 	T& operator*() const {
 		return *get_virt_addr();
 	}
+	/** Access the T at this physical address.
+	 */
 	T* operator->() const {
 		return get_virt_addr();
 	}
 
+	/** Change the address to that of the following T in physical memory.
+	 * \return New address.
+	 */
 	constexpr phys_ptr<T>& operator++() {
 		return *this += 1;
 	}
+	/** Change the address to that of the following T in physical memory.
+	 * \return Old address.
+	 */
 	constexpr phys_ptr<T> operator++(int) {
 		const auto old = *this;
 		operator++();
 		return old;
 	}
+	/** Change the address to that of the previous T in physical memory.
+	 * \return New address.
+	 */
 	constexpr phys_ptr<T>& operator--() {
 		return *this -= 1;
 	}
+	/** Change the address to that of the previous T in physical memory.
+	 * \return Old address.
+	 */
 	constexpr phys_ptr<T> operator--(int) {
 		const auto old = *this;
 		operator--();
 		return old;
 	}
+	/** Move offset Ts forwards in physical memory.
+	 * \return New address.
+	 */
 	constexpr phys_ptr<T>& operator+=(std::ptrdiff_t offset) {
 		return *this = *this + offset;
 	}
+	/** Move offset Ts backwards in physical memory.
+	 * \return New address.
+	 */
 	constexpr phys_ptr<T>& operator-=(std::ptrdiff_t offset) {
 		return *this = *this - offset;
 	}
 
+	/** \return A new phys_ptr refering to the T offset Ts forward from ptr.
+	 */
 	friend constexpr phys_ptr<T> operator+(phys_ptr<T> ptr, std::ptrdiff_t offset) {
 		return phys_ptr<T>{ptr.phys_addr + offset * sizeof(T)};
 	}
+	/** \return A new phys_ptr refering to the T offset Ts forward from ptr.
+	 */
 	friend constexpr phys_ptr<T> operator+(std::ptrdiff_t offset, phys_ptr<T> ptr) {
 		return ptr + offset;
 	}
+	/** \return A new phys_ptr refering to the T offset Ts backwards from ptr.
+	 */
 	friend constexpr phys_ptr<T> operator-(phys_ptr<T> ptr, std::ptrdiff_t offset) {
 		return phys_ptr<T>{ptr.phys_addr - offset * sizeof(T)};
 	}
+	/** \return The numbers of Ts between the two phys_ptr.
+	 */
 	friend constexpr std::ptrdiff_t operator-(phys_ptr<T> a, phys_ptr<T> b) {
 		return (a.phys_addr - b.phys_addr) / sizeof(T);
 	}
 
+	/** \return This physical address, as a uintptr_t.
+	 */
 	constexpr std::uintptr_t get_phys_addr() const {
 		return phys_addr;
 	}
 
+	/** Compare the physical addresses, an address that's before another one in memory is smaller than that one.
+	 */
 	friend constexpr auto operator<=>(phys_ptr<T> a, phys_ptr<T> b) = default;
 
 private:
+	/** The function used inside of the class to get the virtual address that corresponds to this physical address.
+	 */
 	constexpr T* get_virt_addr() const {
 		return reinterpret_cast<T*>(phys_addr + 0xFFFF800000000000);
 	}
 
+	/** This physical address, as a std::uintptr_t
+	 */
 	std::uintptr_t phys_addr;
 };
 
-- 
2.47.0