From 83f0c01e299e95af75acf4375f1f6f3617ca71c1 Mon Sep 17 00:00:00 2001 From: Medusa Slockbower Date: Tue, 19 Aug 2025 18:05:09 -0400 Subject: [PATCH] - Fixes for Doxygen Layouts - Changed dynarray indexing to use size_t - Added groups to optional documentation --- README.md | 29 +++++++--- doxy/DoxyLayout.xml | 12 ++-- doxy/custom.css | 7 ++- include/fennec/containers/array.h | 16 ++++-- include/fennec/containers/dynarray.h | 8 +-- include/fennec/containers/graph.h | 31 +++++++++- include/fennec/containers/optional.h | 86 ++++++++++++++++++++-------- include/fennec/core/engine.h | 3 +- planning/CONTENTS.md | 10 +--- 9 files changed, 143 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index bb2d910..ed9ee38 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,9 @@ * [Coding Standards](#coding-standards) * [Building from Source](#building-from-source) * [Building from Terminal](#building-from-terminal) - * [Debian](#debian) - * [Fedora](#fedora-dnf) → `dnf` + * [Debian](#debian) → `apt` + * [Arch](#arch) → `pacman` + * [Fedora](#fedora) → `dnf` * [Building on Windows](#building-on-windows) * [Running the Test Suite](#running-the-test-suite) * [Usage](#usage) @@ -158,7 +159,7 @@ If you wish to build for Windows *and* Linux, your options are WSL or Dual Boot. On Debian-based distributions, you can install dependencies using the following command: ```shell sudo apt install build-essential cmake ninja-build libglew-dev valgrind -git submodule update --init --recursive +git submodule update --force --init --recursive --remote ``` for Doxygen run: @@ -166,13 +167,27 @@ for Doxygen run: sudo apt install doxygen graphviz ``` - -#### Fedora (`dnf`) + +#### Arch -On Debian-based distributions, you can install dependencies using the following command: +On Arch-based distributions, you can install dependencies using the following command: +```shell +sudo pacman -S base-devel cmake ninja glew valgrind +git submodule update --force --init --recursive --remote +``` + +for Doxygen run: +```shell +sudo pacman -S doxygen graphviz +``` + + +#### Fedora + +On Fedora-based distributions, you can install dependencies using the following command: ```shell sudo dnf install build-essential g++ cmake ninja-build glew-devel valgrind -git submodule update --init --recursive +git submodule update --force --init --recursive --remote ``` for Doxygen run: diff --git a/doxy/DoxyLayout.xml b/doxy/DoxyLayout.xml index 5e7c7bd..112023d 100644 --- a/doxy/DoxyLayout.xml +++ b/doxy/DoxyLayout.xml @@ -49,6 +49,7 @@ + @@ -83,7 +84,6 @@ - @@ -105,6 +105,7 @@ + @@ -121,7 +122,6 @@ - @@ -150,6 +150,7 @@ + @@ -167,7 +168,6 @@ - @@ -185,6 +185,7 @@ + @@ -210,7 +211,6 @@ - @@ -237,6 +237,7 @@ + @@ -246,7 +247,6 @@ - @@ -256,10 +256,10 @@ + - diff --git a/doxy/custom.css b/doxy/custom.css index 095b7d1..a169a70 100644 --- a/doxy/custom.css +++ b/doxy/custom.css @@ -286,4 +286,9 @@ html.dark-mode { td.odd_c { background-color: var(--odd-color) -} \ No newline at end of file +} + +a + h2.groupheader { + display:none; +} + diff --git a/include/fennec/containers/array.h b/include/fennec/containers/array.h index 6b3dad8..b8bd432 100644 --- a/include/fennec/containers/array.h +++ b/include/fennec/containers/array.h @@ -151,21 +151,29 @@ struct array /// /// \returns A pointer to the first element of the array - constexpr ValueT* begin() { return elements; } + constexpr ValueT* begin() { + return elements; + } /// /// \returns A pointer to one after the end of the array - constexpr ValueT* end() { return elements + ElemV; } + constexpr ValueT* end() { + return elements + ElemV; + } /// /// \returns A const-qualified pointer to the first element of the array - constexpr const ValueT* begin() const { return elements; } + constexpr const ValueT* begin() const { + return elements; + } /// /// \returns A const-qualified pointer to one after the end of the array - constexpr const ValueT* end() const { return elements + ElemV; } + constexpr const ValueT* end() const { + return elements + ElemV; + } /// @} diff --git a/include/fennec/containers/dynarray.h b/include/fennec/containers/dynarray.h index 65dee72..f7cca36 100644 --- a/include/fennec/containers/dynarray.h +++ b/include/fennec/containers/dynarray.h @@ -236,8 +236,8 @@ public: /// \brief Array Access Operator /// \param i The index to access /// \returns A reference to the element at index `i` - constexpr TypeT& operator[](int i) { - assertd(i >= 0 and size_t(i) < _size, "Array Out of Bounds"); + constexpr TypeT& operator[](size_t i) { + assertd(i < _size, "Array Out of Bounds"); return _alloc.data()[i]; } @@ -245,8 +245,8 @@ public: /// \brief Array Access Operator (const) /// \param i The index to access /// \returns A const qualified reference to the element at index `i` - constexpr const TypeT& operator[](int i) const { - assertd(i >= 0 and size_t(i) < _size, "Array Out of Bounds"); + constexpr const TypeT& operator[](size_t i) const { + assertd(i < _size, "Array Out of Bounds"); return _alloc.data()[i]; } diff --git a/include/fennec/containers/graph.h b/include/fennec/containers/graph.h index d52ac53..0841a28 100644 --- a/include/fennec/containers/graph.h +++ b/include/fennec/containers/graph.h @@ -60,7 +60,19 @@ namespace fennec /// Graphs contain nodes (sometimes called vertices) and connections. Graphs are either directed /// or undirected. This structure allows the creation of both directed and undirected connections. As /// far as what that means; a directed graph means that connections have direction, where there are connections -/// that are "to" and "from," rather than "between" which is used in undirected graphs There are . +/// that are "to" and "from," rather than "between" which is used in undirected graphs. +/// +/// An undirected graph is connected if there is a path between every pair of nodes in the graph. +/// +/// A directed graph is weakly connected if replacing all of its directed connections with undirected connections would +/// produce a connected graph. We will call this "disjointed" +/// +/// A directed graph is semi-connected if there is a directed path p for `u` → `v` *or* `v` → `u` for every +/// pair of nodes `u, v`. We will call this "unilateral" +/// +/// A directed graph is strongly-connected if there is a directed path p for `u` → `v` *and* `v` → `u` for every pair +/// of nodes `u, v`. We will call this "connected" +/// /// \tparam NodeT The type associated with each node /// \tparam WeightT The type associated with each connection template @@ -143,7 +155,7 @@ public: return num_nodes() == 0; } - // TODO: connected, disjoint + // TODO: connected, disjoint, unilateral /// @} @@ -252,6 +264,9 @@ public: /// /// \brief Getter for a list of nodes `x` that `node` has a connection to and from `x...` and share the same weight + /// "Joined" connections may also be referred to as "undirected." A joined, or undirected, connection may be + /// turned into a directed connection by changing the weight object associated with the connection, or by + /// removing one of the sub-connections. /// \param node The id of the node /// \returns A list containing all nodes `x` that have symmetric connections with `node` list joined(size_t node) { @@ -268,6 +283,18 @@ public: return res; } + /// + /// \brief Getter for the internal storage of mapped connections from this node + /// Use this when you want to iterate over connections that start from this node. + /// \param node The id of the node + /// \returns A pointer to a map containing connections mapped from this node + const auto* connections(size_t node) { + if (empty() || node >= _conn_map.size()) { + return nullptr; + } + return &_conn_map[node]; + } + /// @} diff --git a/include/fennec/containers/optional.h b/include/fennec/containers/optional.h index 9de3d57..cbc3f47 100644 --- a/include/fennec/containers/optional.h +++ b/include/fennec/containers/optional.h @@ -48,6 +48,9 @@ public: // Constructors ======================================================================================================== + /// \name Constructors & Destructor + /// @{ + /// /// \brief Default Constructor constexpr optional() @@ -116,9 +119,34 @@ public: } } + /// @} + + +// Properties ========================================================================================================== + + /// \name Properties + /// @{ + + /// + /// \brief Implicit Boolean Check, returns `true` when there is a value contained + constexpr operator bool() const { + return _set; + } + + /// + /// \returns `true` when there is no held value, `false` otherwise. + constexpr bool empty() const { + return not _set; + } + + /// @} + // Assignment Operators ================================================================================================ + /// \name Assignment + /// @{ + /// /// \brief Fundamental Type Assignment /// \param val The value to set with @@ -195,34 +223,13 @@ public: return *this; } - /// - /// \brief Emplace Assignment - /// \val The optional to move - template - constexpr T& emplace(ArgsT&&...args) { - if (_set) { - _val = T(fennec::forward(args)...); - } else { - fennec::construct(&_val, fennec::forward(args)...); - _set = true; - } - return _val; - } - - /// - /// \brief Reset the Optional - void reset() { - this->operator=(nullopt); - } + /// @} -// Operators =========================================================================================================== +// Access ============================================================================================================== - /// - /// \brief Implicit Boolean Check, returns `true` when there is a value contained - constexpr operator bool() const { - return _set; - } + /// \name Access + /// @{ /// /// \returns A pointer to the value, `nullptr` if there is no value @@ -268,6 +275,35 @@ public: return _val; } + /// @} + +// Modifiers =========================================================================================================== + + /// \name Modifiers + /// @{ + + /// + /// \brief Emplace Assignment + /// \val The optional to move + template + constexpr T& emplace(ArgsT&&...args) { + if (_set) { + _val = T(fennec::forward(args)...); + } else { + fennec::construct(&_val, fennec::forward(args)...); + _set = true; + } + return _val; + } + + /// + /// \brief Reset the Optional + void reset() { + this->operator=(nullopt); + } + + /// @} + diff --git a/include/fennec/core/engine.h b/include/fennec/core/engine.h index faa4fca..ac52d03 100644 --- a/include/fennec/core/engine.h +++ b/include/fennec/core/engine.h @@ -36,7 +36,8 @@ /// 2. \ref building-from-source "Building from Source" /// 1. \ref building-from-terminal "Building from Terminal" /// 1. \ref debian "Debian" -/// 2. \ref fedora-dnf "Fedora" +/// 2. \ref arch "Arch" +/// 3. \ref fedora "Fedora" /// 2. \ref building-on-windows "Building on Windows" /// 3. \ref running-the-test-suite "Running the Test Suite" /// 4. \ref usage "Usage" diff --git a/planning/CONTENTS.md b/planning/CONTENTS.md index d868dea..6695cf1 100644 --- a/planning/CONTENTS.md +++ b/planning/CONTENTS.md @@ -55,17 +55,9 @@ denote implementation and testing progress. The symbols are defined below. | Symbol | Meaning | Notes | |:------:|:------------------------|:----------------------------------------------------------| | ✅ | Completed | Complete implementation and all tests passing. | -| 🚧 | Partial | Partial implementation and all tests implemented passing. | -| ❓ | Untested | Not tested | +| 🚧 | Partial | Partial implementation and all tests implemented passing. | | ⛔ | Unimplemented / Failing | Not implemented or any test is failing. | -| Implemented / Passed | ✅ | 🚧 | ❓ | ⛔ | -|:--------------------:|--------------------------------------------------------------------|-------------------------------------------------------------------------------|---------|-----------------| -| ✅ | Implemented and Passing | Invalid | Invalid | Not Implemented | -| 🚧 | Implemented and Partial Testing with all implemented tests passing | Partial Implementation and Partial Testing with all implemented tests passing | Invalid | Not Implemented | -| ❓ | Implemented and Untested | Partial Implementation and Untested | Invalid | Not Implemented | -| ⛔ | Implemented and Any Test is Failing | Partial Implementation and any test is Failing | Invalid | Not Implemented | - ## Libraries