YT-CPPGL-46: Library prerelease cleanup

- Updated the licence file to include the project info
- Added copyright info in all implementation files
- Added the `check_licence.py` script and the `licence` workflow 
- Corrected the vertex degree getting fuctionality
- Removed redundant comments and added/extended comments in some places to make the code more readable
- Removed redunant include statements
- Replaced post{increment/decrement} operators with pre{increment/decrement} operators where possible
- Replaced magic values with constants where possible

.github/workflows/format.yaml

@@ -5,6 +5,7 @@ on:
       - '*'
     paths:
       - .github/workflows/format.yaml
+      - scripts/format.py
       - include/**
       - tests/include/**
       - tests/source/**

.github/workflows/licence.yaml

@@ -0,0 +1,29 @@
+name: licence
+on:
+  push:
+    branches:
+      - '*'
+    paths:
+      - .github/workflows/licence.yaml
+      - scripts/check_licence.py
+      - include/**
+
+
+jobs:
+  build:
+    name: Test code formatting
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Test formatting
+        shell: bash
+        run: |
+          python3 scripts/check_licence.py

.gitignore

@@ -9,5 +9,8 @@
 # documentation files
 documentation/
 
+# python temporary files
+**/__pycache__/
+
 # other
 *tmp*/

LICENSE

@@ -1,6 +1,8 @@
 MIT License
 
 Copyright (c) 2024 Jakub Musiał
+Project: "CPP-GL: General purpose header-only template graph library for C++20 and newer standards."
+https://github.com/SpectraL519/cpp-gl
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

include/gl/algorithm/breadth_first_search.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "constants.hpp"

include/gl/algorithm/coloring.hpp

@@ -1,7 +1,10 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "detail/bfs_impl.hpp"
-#include "gl/types/properties.hpp"
 
 namespace gl::algorithm {
 
@@ -32,10 +35,10 @@ template <
         const bool is_bipartite = detail::bfs_impl(
             graph,
             detail::init_range(root_id),
-            detail::constant_unary_predicate<true>(), // visit pred
+            detail::constant_unary_predicate<true>(), // visit predicate
             detail::constant_binary_predicate<true>(), // visit callback
             [&coloring](const vertex_type& vertex, const edge_type& in_edge)
-                -> std::optional<bool> { // enqueue pred
+                -> std::optional<bool> { // enqueue predicate
                 if (in_edge.is_loop())
                     return false;
 

include/gl/algorithm/constants.hpp

@@ -1,5 +1,11 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
+#include "gl/constants.hpp"
+
 #include <optional>
 
 namespace gl::algorithm {

include/gl/algorithm/deapth_first_search.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "constants.hpp"

include/gl/algorithm/detail/bfs_impl.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "common.hpp"

include/gl/algorithm/detail/common.hpp

@@ -1,7 +1,10 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "gl/algorithm/types.hpp"
-#include "gl/graph.hpp"
 
 namespace gl::algorithm::detail {
 

include/gl/algorithm/detail/dfs_impl.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "common.hpp"
@@ -25,9 +29,11 @@ void dfs_impl(
     if (not visit_vertex_pred(root_vertex))
         return;
 
+    // prepare the vertex stack
     vertex_stack_type vertex_stack;
     vertex_stack.emplace(root_vertex.id());
 
+    // search the graph
     while (not vertex_stack.empty()) {
         const auto vinfo = vertex_stack.top();
         vertex_stack.pop();
@@ -75,6 +81,7 @@ void rdfs_impl(
 
     visit(vertex, source_id);
 
+    // recursively search vertices adjacent to the current vertex
     const auto vertex_id = vertex.id();
     for (const auto& edge : graph.adjacent_edges(vertex_id)) {
         const auto& incident_vertex = edge.incident_vertex(vertex);

include/gl/algorithm/dijkstra.hpp

@@ -1,8 +1,11 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "detail/bfs_impl.hpp"
 #include "gl/graph_utility.hpp"
-#include "gl/types/properties.hpp"
 
 #include <deque>
 
@@ -59,7 +62,6 @@ template <
     paths.predecessors.at(source_id).emplace(source_id);
     paths.distances[source_id] = distance_type{};
 
-    constexpr distance_type min_edge_weight_threshold = 0ull;
     std::optional<types::const_ref_wrap<edge_type>> negative_edge;
 
     detail::pq_bfs_impl(
@@ -68,15 +70,15 @@ template <
             return paths.distances[lhs.id] > paths.distances[rhs.id];
         },
         detail::init_range(source_id),
-        detail::constant_unary_predicate<true>(), // visit pred
+        detail::constant_unary_predicate<true>(), // visit predicate
         detail::constant_binary_predicate<true>(), // visit callback
         [&paths, &negative_edge](const vertex_type& vertex, const edge_type& in_edge)
-            -> std::optional<bool> { // enqueue pred
+            -> std::optional<bool> { // enqueue predicate
             const auto vertex_id = vertex.id();
             const auto source_id = in_edge.incident_vertex(vertex).id();
 
             const auto edge_weight = get_weight<GraphType>(in_edge);
-            if (edge_weight < min_edge_weight_threshold) {
+            if (edge_weight < constants::zero) {
                 negative_edge = std::cref(in_edge);
                 return std::nullopt;
             }

include/gl/algorithm/mst.hpp

@@ -1,11 +1,12 @@
-#pragma once
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "constants.hpp"
 #include "detail/common.hpp"
-#include "gl/types/properties.hpp"
 
-#include <iostream>
 #include <queue>
 
 namespace gl::algorithm {
@@ -17,11 +18,11 @@ struct mst_descriptor {
     using weight_type = types::vertex_distance_type<graph_type>;
 
     mst_descriptor(const types::size_type n_vertices) {
-        edges.reserve(n_vertices - 1ull);
+        edges.reserve(n_vertices - constants::one);
     }
 
     std::vector<types::const_ref_wrap<edge_type>> edges;
-    weight_type weight = static_cast<weight_type>(0ll);
+    weight_type weight = static_cast<weight_type>(constants::zero);
 };
 
 template <
@@ -64,25 +65,24 @@ template <
     };
 
     // insert the edges adjacent to the root vertex to the queue
-    const types::id_type root_id = root_id_opt.value_or(0ull);
+    const types::id_type root_id = root_id_opt.value_or(constants::zero);
 
     for (const auto& edge : graph.adjacent_edges(root_id))
         edge_queue.emplace(edge, root_id);
 
     // mark the root vertex as visited
     visited[root_id] = true;
-    types::size_type n_vertices_in_mst = 1ull;
+    types::size_type n_vertices_in_mst = constants::one;
 
     // find the mst
-    constexpr distance_type min_edge_weight_threshold = 0ull;
     while (n_vertices_in_mst < n_vertices) {
         const auto min_edge_info = edge_queue.top();
         edge_queue.pop();
 
         const auto& min_edge = min_edge_info.edge.get();
         const auto min_weight = get_weight<GraphType>(min_edge);
 
-        if (min_weight < min_edge_weight_threshold)
+        if (min_weight < constants::zero)
             throw std::invalid_argument(std::format(
                 "[alg::prim_mst] Found an edge with a negative weight: [{}, {} | w={}]",
                 min_edge.first_id(),
@@ -92,13 +92,15 @@ template <
 
         const auto& dest_vertex_id = get_other_vertex_id(min_edge, min_edge_info.source_id);
         if (not visited[dest_vertex_id]) {
+            // add the minimum weight edge to the mst
             mst.edges.emplace_back(min_edge);
             mst.weight += min_weight;
 
             visited[dest_vertex_id] = true;
             ++n_vertices_in_mst;
         }
 
+        // enqueue all edges adjacent to the destination vertex if they lead to unvisited verties
         for (const auto& edge : graph.adjacent_edges(dest_vertex_id))
             if (not visited[get_other_vertex_id(edge, dest_vertex_id)])
                 edge_queue.emplace(edge, dest_vertex_id);

include/gl/algorithm/topological_sort.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "detail/bfs_impl.hpp"
@@ -39,15 +43,15 @@ template <
     detail::bfs_impl(
         graph,
         source_vertex_list,
-        detail::constant_unary_predicate<true>(), // visit pred
+        detail::constant_unary_predicate<true>(), // visit predicate
         [&topological_order](
             const vertex_type& vertex, const types::id_type source_id
         ) { // visit callback
             topological_order.push_back(vertex.id());
             return true;
         },
         [&vertex_in_deg_list](const vertex_type& vertex, const edge_type& in_edge)
-            -> std::optional<bool> { // enqueue pred
+            -> std::optional<bool> { // enqueue predicate
             if (in_edge.is_loop())
                 return false;
             return --vertex_in_deg_list[vertex.id()] == constants::default_size;
@@ -59,7 +63,7 @@ template <
     if (topological_order.size() != graph.n_vertices())
         return std::nullopt;
 
-    return topological_order;
+    return topological_order_opt;
 }
 
 } // namespace gl::algorithm

include/gl/algorithm/types.hpp

@@ -1,9 +1,12 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "gl/graph_utility.hpp"
 
 #include <functional>
-#include <vector>
 
 namespace gl {
 

include/gl/algorithms.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "algorithm/breadth_first_search.hpp"

include/gl/attributes/force_inline.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #ifndef gl_attr_force_inline

include/gl/constants.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "types/types.hpp"
@@ -11,6 +15,5 @@ inline constexpr types::size_type two{2ull};
 inline constexpr types::size_type default_size{zero};
 inline constexpr types::size_type begin_idx{zero};
 inline constexpr types::id_type initial_id{zero};
-inline constexpr types::size_type one_element{one};
 
 } // namespace gl::constants

include/gl/decl/graph_traits.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "gl/types/type_traits.hpp"

include/gl/decl/impl_tags.hpp

@@ -1,3 +1,7 @@
+// Copyright (c) 2024 Jakub Musiał
+// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
+// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
+
 #pragma once
 
 #include "gl/edge_tags.hpp"