Added Doxygen comments to AlignedAllocator

Author: azonenberg

scopehal/AlignedAllocator.h

@@ -1,8 +1,8 @@
 /***********************************************************************************************************************
 *                                                                                                                      *
-* libscopehal v0.1                                                                                                     *
+* libscopehal                                                                                                          *
 *                                                                                                                      *
-* Copyright (c) 2012-2021 Andrew D. Zonenberg and contributors                                                         *
+* Copyright (c) 2012-2024 Andrew D. Zonenberg and contributors                                                         *
 * All rights reserved.                                                                                                 *
 *                                                                                                                      *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
@@ -31,6 +31,7 @@
 	@file
 	@author Andrew D. Zonenberg
 	@brief Declaration of AlignedAllocator
+	@ingroup core
  */
 
 #ifndef AlignedAllocator_h
@@ -44,43 +45,87 @@
 	@brief Aligned memory allocator for STL containers
 
 	Based on https://devblogs.microsoft.com/cppblog/the-mallocator/
+
+	@ingroup core
  */
 template <class T, size_t alignment>
 class AlignedAllocator
 {
 public:
 
-	//Standard typedefs
+	///@brief Pointer to the allocated type
 	typedef T* pointer;
+
+	///@brief Const pointer to the allocated type
 	typedef const T* const_pointer;
+
+	///@brief Reference to the allocated type
 	typedef T& reference;
+
+	///@brief Const reference to the allocated type
 	typedef const T& const_reference;
+
+	///@brief The allocated type
 	typedef T value_type;
+
+	///@brief Type of the size of an allocated object
 	typedef size_t size_type;
+
+	///@brief Type of the difference between two allocated pointers
 	typedef ptrdiff_t difference_type;
 
-	//Overloads in case somebody overloaded the unary operator&()
-	//(which is pretty weird but the spec allows it)
+	/**
+		@brief Get the address of an object
+
+		Overloaded in case somebody overloaded the unary operator&()
+		(which is pretty weird but the spec allows it)
+
+		@param rhs	The object to get the address of
+	 */
 	T* address(T& rhs)
 	{ return &rhs; }
 
+	/**
+		@brief Get the address of an object
+
+		Overloaded in case somebody overloaded the unary operator&()
+		(which is pretty weird but the spec allows it)
+
+		@param rhs	The object to get the address of
+	 */
 	const T* address(T& rhs) const
 	{ return &rhs; }
 
+	/**
+		@brief Get the max possible allocation size the allocator supports
+
+		(Does not necessarily mean that we have enough RAM to do so, only enough address space)
+	 */
 	size_t max_size() const
 	{ return (static_cast<size_t>(0) - static_cast<size_t>(1)) / sizeof(T); }
 
-	//RTTI and construction helpers
+	///@brief Rebind to a different type of allocator
 	template<typename U>
 	struct rebind
 	{
 		typedef AlignedAllocator<U, alignment> other;
 	};
 
+	/**
+		@brief Check if two allocators are the same
+
+		@param other	The other object
+	 */
 	bool operator!=(const AlignedAllocator& other) const
 	{ return !(*this == other); }
 
 	//Look at that, a placement new! First time I've ever used one.
+	/**
+		@brief Construct an object in-place given a reference one
+
+		@param p	Destination object
+		@param t	Source object
+	 */
 	void construct(T* const p, const T& t) const
 	{ new( static_cast<void*>(p) ) T(t); }
 
@@ -106,7 +151,11 @@ class AlignedAllocator
 	~AlignedAllocator()
 	{}
 
-	//Now for the fun part
+	/**
+		@brief Allocate a block of memory
+
+		@param n	Size in bytes (internally rounded up to our alignment)
+	 */
 	T* allocate(size_t n) const
 	{
 		//Fail if we got an invalid size
@@ -136,7 +185,13 @@ class AlignedAllocator
 		return ret;
 	}
 
-	void deallocate(T* const p, const size_t /*unused*/) const
+	/**
+		@brief	Free a block of memory
+
+		@param p		Block to free
+		@param unused	Size of block (ignored)
+	 */
+	void deallocate(T* const p, [[maybe_unused]] const size_t unused) const
 	{
 #ifdef _WIN32
 		_aligned_free(p);
@@ -145,13 +200,23 @@ class AlignedAllocator
 #endif
 	}
 
-	//convenience wrapper
+	/**
+		@brief Free a single object
+
+		@param p	Object to free
+	 */
 	void deallocate(T* const p) const
 	{ deallocate(p, 1); }
 
 	//Not quite sure what this is for but apparently we need it?
+	/**
+		@brief Allocate an object
+
+		@param n	Size in bytes
+		@param hint	Ignored
+	 */
 	template<typename U>
-	T* allocate(const size_t n, const U* /* const hint */ const)
+	T* allocate(const size_t n, [[maybe_unused]] const U* const hint)
 	{ return allocate(n); }
 
 	//Disallow assignment

scopehal/AntikernelLogicAnalyzer.h

@@ -1,8 +1,8 @@
 /***********************************************************************************************************************
 *                                                                                                                      *
-* libscopehal v0.1                                                                                                     *
+* libscopehal                                                                                                          *
 *                                                                                                                      *
-* Copyright (c) 2012-2023 Andrew D. Zonenberg and contributors                                                         *
+* Copyright (c) 2012-2024 Andrew D. Zonenberg and contributors                                                         *
 * All rights reserved.                                                                                                 *
 *                                                                                                                      *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the     *
@@ -31,6 +31,7 @@
 	@file
 	@author Andrew D. Zonenberg
 	@brief Declaration of AntikernelLogicAnalyzer
+	@ingroup scopedrivers
  */
 
 #ifndef AntikernelLogicAnalyzer_h