From 302d883f34864bc66a5e04532ae27d7e89fd94e8 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Wed, 28 Jan 2026 09:31:13 +0100
Subject: style: Add 3-line descriptive headers to all source files

This commit applies a new project-wide rule that every source file must begin with a concise 3-line comment header describing its purpose.

- Updated CONTRIBUTING.md with the new rule.

- Applied headers to all .cc and .h files in src/ and tools/.

- Fixed various minor compilation errors and missing includes discovered during the header update process.
---
 tools/asset_packer.cc | 17 ++++++++++-------
 tools/spectool.cc     |  6 +++++-
 tools/specview.cc     |  7 ++++++-
 3 files changed, 21 insertions(+), 9 deletions(-)

(limited to 'tools')

diff --git a/tools/asset_packer.cc b/tools/asset_packer.cc
index a67ddcc..8696646 100644
--- a/tools/asset_packer.cc
+++ b/tools/asset_packer.cc
@@ -1,3 +1,7 @@
+// This file is part of the 64k demo project.
+// It implements the asset packer tool for demoscene resource management.
+// Converts external files into embedded C++ byte arrays.
+
 #include <fstream>
 #include <iostream>
 #include <map>
@@ -39,8 +43,8 @@ int main(int argc, char *argv[]) {
 
   // Generate assets.h
   assets_h_file << "#pragma once\n";
-  assets_h_file << "#include <cstdint>\n";
-  assets_h_file << "#include <cstddef>\n\n";
+  assets_h_file << "#include <cstddef>\n";
+  assets_h_file << "#include <cstdint>\n\n";
   assets_h_file << "enum class AssetId : uint16_t {\n";
 
   // Generate assets_data.cc header
@@ -109,8 +113,8 @@ int main(int argc, char *argv[]) {
                           << (i == buffer.size() - 1 ? "" : ", ");
     }
     assets_data_cc_file << "\n};\n";
-    assets_data_cc_file << "const size_t ASSET_SIZE_" << asset_name << " = "
-                        << buffer.size() << ";\n\n";
+    assets_data_cc_file << "const size_t ASSET_SIZE_" << asset_name
+                        << " = " << buffer.size() << ";\n\n";
 
     asset_id_counter++;
   }
@@ -120,9 +124,8 @@ int main(int argc, char *argv[]) {
   // Generate GetAsset function declaration in assets.h
   assets_h_file << "const uint8_t *GetAsset(AssetId asset_id, size_t *out_size "
                    "= nullptr);\n";
-  assets_h_file
-      << "void DropAsset(AssetId asset_id, const uint8_t *asset); // For lazy "
-         "decompression scaffolding\n";
+  assets_h_file << "void DropAsset(AssetId asset_id, const uint8_t *asset); // "
+                   "For lazy decompression scaffolding\n";
   assets_h_file.close();
 
   // Generate GetAsset function implementation in assets_data.cc
diff --git a/tools/spectool.cc b/tools/spectool.cc
index d2f4e54..e57e77b 100644
--- a/tools/spectool.cc
+++ b/tools/spectool.cc
@@ -1,3 +1,7 @@
+// This file is part of the 64k demo project.
+// It implements the spectool for analyzing audio into spectrograms.
+// Provides both 'analyze' and 'play' modes for spectral data.
+
 #include "audio/audio.h"
 #include "audio/dct.h"
 #include "audio/synth.h"
@@ -161,4 +165,4 @@ int main(int argc, char **argv) {
   }
 
   return 0;
-}
+}
\ No newline at end of file
diff --git a/tools/specview.cc b/tools/specview.cc
index d2ce914..699345f 100644
--- a/tools/specview.cc
+++ b/tools/specview.cc
@@ -1,4 +1,9 @@
+// This file is part of the 64k demo project.
+// It implements the specview tool for visualizing spectrograms.
+// Renders spectral data as ASCII art in the console.
+
 #include <algorithm> // For std::max_element
+#include <math.h>
 #include <stdio.h>
 #include <string.h>
 #include <vector>
@@ -96,4 +101,4 @@ int main(int argc, char **argv) {
   }
 
   return 0;
-}
+}
\ No newline at end of file
-- 
cgit v1.2.3