From ec2d69a6d9d59e5efa1290c125b928f0b866a8a7 Mon Sep 17 00:00:00 2001
From: UnknownShadow200 <unknownshadow200@gmail.com>
Date: Tue, 14 Jun 2022 21:13:23 +1000
Subject: [PATCH] Update some headers to 2022 and improve their comments

---
 src/Animations.h        |  7 ++++---
 src/Builder.h           | 11 ++++++-----
 src/Camera.h            |  6 +++---
 src/Constants.h         |  5 +++--
 src/Core.h              |  5 +++--
 src/Drawer.h            |  5 +++--
 src/EnvRenderer.h       |  5 +++--
 src/Errors.h            |  5 +++--
 src/Funcs.h             |  7 ++++---
 src/HeldBlockRenderer.h |  5 +++--
 src/Http.h              |  7 ++++---
 src/Input.h             |  6 +++---
 src/Lighting.c          | 16 ++++++++--------
 src/Lighting.h          | 18 +++++++++++++-----
 src/Logger.h            |  5 +++--
 src/Options.h           |  5 +++--
 src/Particle.h          |  5 +++--
 src/Physics.h           |  7 ++++---
 src/Picking.h           |  6 ++++--
 src/Platform.h          |  5 +++--
 src/Protocol.h          |  5 +++--
 src/Server.h            |  5 +++--
 src/String.h            | 11 ++++++-----
 src/TexturePack.h       | 11 ++++++-----
 src/Utils.h             |  5 +++--
 src/Vectors.h           |  7 ++++---
 src/Window.h            |  5 +++--
 27 files changed, 111 insertions(+), 79 deletions(-)

diff --git a/src/Animations.h b/src/Animations.h
index dbb742e22..90f6ffe8a 100644
--- a/src/Animations.h
+++ b/src/Animations.h
@@ -1,8 +1,9 @@
 #ifndef CC_ANIMATIONS_H
 #define CC_ANIMATIONS_H
-/* Contains everything relating to texture animations (including default water/lava ones)
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3 
- */
+/* 
+Contains everything relating to texture animations (including default water/lava ones)
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
+*/
 
 struct IGameComponent;
 extern struct IGameComponent Animations_Component;
diff --git a/src/Builder.h b/src/Builder.h
index 90ba377c0..85726c7e7 100644
--- a/src/Builder.h
+++ b/src/Builder.h
@@ -1,12 +1,13 @@
 #ifndef CC_BUILDER_H
 #define CC_BUILDER_H
 #include "Core.h"
-/* Converts a 16x16x16 chunk into a mesh of vertices.
-NormalMeshBuilder:
-   Implements a simple chunk mesh builder, where each block face is a single colour.
-   (whatever lighting engine returns as light colour for given block face at given coordinates)
+/* 
+Converts a 16x16x16 chunk into a mesh of vertices
+  NormalMeshBuilder:
+    Implements a simple chunk mesh builder, where each block face is a single colour
+    (whatever lighting engine returns as light colour for given block face at given coordinates)
 
-Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct ChunkInfo;
 struct IGameComponent;
diff --git a/src/Camera.h b/src/Camera.h
index 0cd67baca..80b86f475 100644
--- a/src/Camera.h
+++ b/src/Camera.h
@@ -1,9 +1,9 @@
 #ifndef CC_CAMERA_H
 #define CC_CAMERA_H
 #include "Vectors.h"
-
-/* Represents a camera, may be first or third person.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/*
+Represents a camera, may be first or third person
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct RayTracer;
 struct Camera;
diff --git a/src/Constants.h b/src/Constants.h
index d3092d0a6..799da5940 100644
--- a/src/Constants.h
+++ b/src/Constants.h
@@ -1,7 +1,8 @@
 #ifndef CC_CONSTANTS_H
 #define CC_CONSTANTS_H
-/* Defines useful constants.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Defines useful constants
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 #define GAME_MAX_CMDARGS 5
diff --git a/src/Core.h b/src/Core.h
index 31bd81f12..c75bd9c23 100644
--- a/src/Core.h
+++ b/src/Core.h
@@ -1,7 +1,8 @@
 #ifndef CC_CORE_H
 #define CC_CORE_H
-/* Core fixed-size integer types, automatic platform detection, and common small structs.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Core fixed-size integer types, automatic platform detection, and common small structs
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 #if _MSC_VER
diff --git a/src/Drawer.h b/src/Drawer.h
index 4bbd5bfc0..9dcb3cfda 100644
--- a/src/Drawer.h
+++ b/src/Drawer.h
@@ -2,8 +2,9 @@
 #define CC_DRAWER_H
 #include "PackedCol.h"
 #include "Vectors.h"
-/* Draws the vertices for a cuboid region.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Draws the vertices for a cuboid region
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct VertexTextured;
 
diff --git a/src/EnvRenderer.h b/src/EnvRenderer.h
index 2270c137a..8460e185d 100644
--- a/src/EnvRenderer.h
+++ b/src/EnvRenderer.h
@@ -1,8 +1,9 @@
 #ifndef CC_ENVRENDERER_H
 #define CC_ENVRENDERER_H
 #include "Core.h"
-/* Renders environment of the map. (clouds, sky, fog, map sides/edges, skybox, rain/snow)
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Renders environment of the map (clouds, sky, fog, map sides/edges, skybox, rain/snow)
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct IGameComponent;
 extern struct IGameComponent EnvRenderer_Component;
diff --git a/src/Errors.h b/src/Errors.h
index 551084fab..b37a56dc7 100644
--- a/src/Errors.h
+++ b/src/Errors.h
@@ -1,7 +1,8 @@
 #ifndef CC_ERRORS_H
 #define CC_ERRORS_H
-/* Contains list of internal ClassiCube errors.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/*
+Provides a list list of internal ClassiCube errors
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 /* NOTE: When adding errors, remember to keep Logger.c up to date! */
diff --git a/src/Funcs.h b/src/Funcs.h
index 0531f3dfc..d3b24684f 100644
--- a/src/Funcs.h
+++ b/src/Funcs.h
@@ -1,9 +1,10 @@
 #ifndef CC_FUNCS_H
 #define CC_FUNCS_H
 #include "Core.h"
-/* Simple function implementations
-   NOTE: doing min(x++, y) etc will increment x twice!
-  Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Simple function implementations
+  NOTE: doing min(x++, y) etc will increment x twice!
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 #define min(x, y) ((x) < (y) ? (x) : (y))
diff --git a/src/HeldBlockRenderer.h b/src/HeldBlockRenderer.h
index f30b7c999..b675efee3 100644
--- a/src/HeldBlockRenderer.h
+++ b/src/HeldBlockRenderer.h
@@ -1,8 +1,9 @@
 #ifndef CC_HELDBLOCKRENDERER_H
 #define CC_HELDBLOCKRENDERER_H
 #include "Core.h"
-/* Implements rendering of held block/arm at bottom right of game.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Renders the held block/arm at bottom right of game
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct IGameComponent;
 extern struct IGameComponent HeldBlockRenderer_Component;
diff --git a/src/Http.h b/src/Http.h
index eff04a8ac..ae0824177 100644
--- a/src/Http.h
+++ b/src/Http.h
@@ -2,9 +2,10 @@
 #define CC_HTTP_H
 #include "Constants.h"
 #include "Core.h"
-/* Aysnchronously performs http GET, HEAD, and POST requests.
-   Typically this is used to download skins, texture packs, etc.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Aysnchronously performs http GET, HEAD, and POST requests
+  Typically this is used to download skins, texture packs, etc
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct IGameComponent;
 struct ScheduledTask;
diff --git a/src/Input.h b/src/Input.h
index 3d5fa1437..4f0490099 100644
--- a/src/Input.h
+++ b/src/Input.h
@@ -1,9 +1,9 @@
 #ifndef CC_INPUT_H
 #define CC_INPUT_H
 #include "Core.h"
-/* Manages keyboard, mouse, and touch state.
-   Raises events when keys are pressed etc, and implements base handlers for them.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Manages input state, raising input related events, and base input handling
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct IGameComponent;
 struct StringsBuffer;
diff --git a/src/Lighting.c b/src/Lighting.c
index 2eedbd42b..2e15c2dd3 100644
--- a/src/Lighting.c
+++ b/src/Lighting.c
@@ -360,12 +360,12 @@ static void ClassicLighting_LightHint(int startX, int startZ) {
 	}
 }
 
-static void ClassicLighting_OnReset(void) {
+static void ClassicLighting_FreeState(void) {
 	Mem_Free(classic_heightmap);
 	classic_heightmap = NULL;
 }
 
-static void ClassicLighting_OnNewMapLoaded(void) {
+static void ClassicLighting_AllocState(void) {
 	classic_heightmap = (cc_int16*)Mem_TryAlloc(World.Width * World.Length, 2);
 	if (classic_heightmap) {
 		ClassicLighting_Refresh();
@@ -388,9 +388,9 @@ static void ClassicLighting_SetActive(void) {
 	Lighting.Color_XSide_Fast  = ClassicLighting_Color_XSide_Fast;
 	Lighting.Color_ZSide_Fast  = ClassicLighting_Color_ZSide_Fast;
 
-	Lighting.HandleReset = ClassicLighting_OnReset;
-	Lighting.HandleNewMapLoaded = ClassicLighting_OnNewMapLoaded;
-	Lighting.LightHint   = ClassicLighting_LightHint;
+	Lighting.FreeState  = ClassicLighting_FreeState;
+	Lighting.AllocState = ClassicLighting_AllocState;
+	Lighting.LightHint  = ClassicLighting_LightHint;
 }
 
 
@@ -398,9 +398,9 @@ static void ClassicLighting_SetActive(void) {
 *---------------------------------------------------Lighting component----------------------------------------------------*
 *#########################################################################################################################*/
 
-static void OnInit(void)  { ClassicLighting_SetActive(); }
-static void OnReset(void) { Lighting.HandleReset(); }
-static void OnNewMapLoaded(void) { Lighting.HandleNewMapLoaded(); }
+static void OnInit(void)         { ClassicLighting_SetActive(); }
+static void OnReset(void)        { Lighting.FreeState(); }
+static void OnNewMapLoaded(void) { Lighting.AllocState(); }
 
 struct IGameComponent Lighting_Component = {
 	OnInit,  /* Init  */
diff --git a/src/Lighting.h b/src/Lighting.h
index 20219593d..bbe823641 100644
--- a/src/Lighting.h
+++ b/src/Lighting.h
@@ -1,16 +1,22 @@
 #ifndef CC_WORLDLIGHTING_H
 #define CC_WORLDLIGHTING_H
 #include "PackedCol.h"
-/* Manages lighting of blocks in the world
-ClassicLighting: Uses a simple heightmap, where each block is either in sun or shadow.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/*
+Abstracts lighting of blocks in the world
+  Built-in lighting engines:
+  - ClassicLighting: Uses a simple heightmap, where each block is either in sun or shadow
+
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct IGameComponent;
 extern struct IGameComponent Lighting_Component;
 
 CC_VAR extern struct _Lighting {
-	void (*HandleReset)(void);
-	void (*HandleNewMapLoaded)(void);
+	/* Releases/Frees the per-level lighting state */
+	void (*FreeState)(void);
+	/* Allocates the per-level lighting state */
+	/*  (called after map has been fully loaded) */
+	void (*AllocState)(void);
 	/* Equivalent to (but far more optimised form of)
 	* for x = startX; x < startX + 18; x++
 	*   for z = startZ; z < startZ + 18; z++
@@ -20,6 +26,8 @@ CC_VAR extern struct _Lighting {
 	/* Called when a block is changed to update internal lighting state. */
 	/* NOTE: Implementations ***MUST*** mark all chunks affected by this lighting change as needing to be refreshed. */
 	void (*OnBlockChanged)(int x, int y, int z, BlockID oldBlock, BlockID newBlock);
+	/* Invalidates/Resets lighting state for all of the blocks in the world */
+	/*  (e.g. because a block changed whether it is full bright or not) */
 	void (*Refresh)(void);
 
 	/* Returns whether the block at the given coordinates is fully in sunlight. */
diff --git a/src/Logger.h b/src/Logger.h
index 8e999c3eb..8940719af 100644
--- a/src/Logger.h
+++ b/src/Logger.h
@@ -1,8 +1,9 @@
 #ifndef CC_LOGGER_H
 #define CC_LOGGER_H
 #include "Core.h"
-/* Support methods for logging errors.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Logs warnings/errors and also abstracts platform specific logging for fatal errors
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 typedef cc_bool (*Logger_DescribeError)(cc_result res, cc_string* dst);
diff --git a/src/Options.h b/src/Options.h
index f889f5516..51a57e815 100644
--- a/src/Options.h
+++ b/src/Options.h
@@ -1,8 +1,9 @@
 #ifndef CC_OPTIONS_H
 #define CC_OPTIONS_H
 #include "Core.h"
-/* Manages loading and saving options.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Manages loading and saving options
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 #define OPT_MUSIC_VOLUME "musicvolume"
diff --git a/src/Particle.h b/src/Particle.h
index 620609e84..5ad12e74c 100644
--- a/src/Particle.h
+++ b/src/Particle.h
@@ -2,8 +2,9 @@
 #define CC_PARTICLE_H
 #include "Vectors.h"
 #include "PackedCol.h"
-/* Represents particle effects, and manages rendering and spawning particles.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Represents particle effects, and manages rendering and spawning particles
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 struct IGameComponent;
diff --git a/src/Physics.h b/src/Physics.h
index afb77319a..114516d87 100644
--- a/src/Physics.h
+++ b/src/Physics.h
@@ -1,11 +1,12 @@
 #ifndef CC_PHYSICS_H
 #define CC_PHYSICS_H
 #include "Vectors.h"
-/* Contains:
+/* 
+Provides various physics related structs and methods such as:
    - An axis aligned bounding box, and various methods related to them.
    - Various methods for intersecting geometry.
-   - Calculates all possible blocks that a moving entity can intersect with.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+   - Calculates all possible blocks that a moving entity can intersect with
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct Entity;
 
diff --git a/src/Picking.h b/src/Picking.h
index 4e2a540f1..d57bf8545 100644
--- a/src/Picking.h
+++ b/src/Picking.h
@@ -1,8 +1,10 @@
 #ifndef CC_PICKING_H
 #define CC_PICKING_H
 #include "Vectors.h"
-/* Data for picking/selecting block by the user, and clipping the camera.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Provides ray tracer functionality for calculating picking/selecting intersection
+  e.g. calculating block selected in the world by the user, clipping the camera
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 /* Implements a voxel ray tracer
diff --git a/src/Platform.h b/src/Platform.h
index 7bd8df737..fc43cab05 100644
--- a/src/Platform.h
+++ b/src/Platform.h
@@ -1,8 +1,9 @@
 #ifndef CC_PLATFORM_H
 #define CC_PLATFORM_H
 #include "Core.h"
-/* Abstracts platform specific memory management, I/O, etc.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Abstracts platform specific memory management, I/O, etc
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct DateTime;
 
diff --git a/src/Protocol.h b/src/Protocol.h
index 9e6e39361..e4480a7a0 100644
--- a/src/Protocol.h
+++ b/src/Protocol.h
@@ -1,8 +1,9 @@
 #ifndef CC_PROTOCOL_H
 #define CC_PROTOCOL_H
 #include "Vectors.h"
-/* Implements network protocols for original classic, CPE, and WoM textures.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Implements network protocols for original classic, CPE, and WoM textures
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 struct RayTracer;
 
diff --git a/src/Server.h b/src/Server.h
index bd24c3d9a..1c8fc40f4 100644
--- a/src/Server.h
+++ b/src/Server.h
@@ -1,8 +1,9 @@
 #ifndef CC_SERVERCONNECTION_H
 #define CC_SERVERCONNECTION_H
 #include "Vectors.h"
-/* Represents a connection to either a multiplayer or an internal singleplayer server.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Represents a connection to either a multiplayer or an internal singleplayer server
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 struct IGameComponent;
diff --git a/src/String.h b/src/String.h
index 93c0606ff..e57d4b33b 100644
--- a/src/String.h
+++ b/src/String.h
@@ -1,11 +1,12 @@
 #ifndef CC_STRING_H
 #define CC_STRING_H
 #include "Core.h"
-/* Implements operations for a string.
-   Also implements conversions betweens strings and numbers.
-   Also implements converting code page 437 indices to/from unicode.
-   Also implements wrapping a single line of text into multiple lines.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Provides various string related operations
+   Also provides conversions betweens strings and numbers
+   Also provides converting code page 437 indices to/from unicode
+   Also provides wrapping a single line of text into multiple lines
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 #define STRING_INT_CHARS 24
diff --git a/src/TexturePack.h b/src/TexturePack.h
index 918ceeaec..37a0521f7 100644
--- a/src/TexturePack.h
+++ b/src/TexturePack.h
@@ -1,11 +1,12 @@
 #ifndef CC_TEXPACKS_H
 #define CC_TEXPACKS_H
 #include "Bitmap.h"
-/* Contains everything relating to texture packs.
-	- Extracting the textures from a .zip archive
-	- Caching terrain atlases and texture packs to avoid redundant downloads
-	- Terrain atlas (including breaking it down into multiple 1D atlases)
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3 
+/* 
+Contains everything relating to texture packs
+  - Extracting the textures from a .zip archive
+  - Caching terrain atlases and texture packs to avoid redundant downloads
+  - Terrain atlas (including breaking it down into multiple 1D atlases)
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 struct Stream;
diff --git a/src/Utils.h b/src/Utils.h
index f86f4105c..e9f916a90 100644
--- a/src/Utils.h
+++ b/src/Utils.h
@@ -1,8 +1,9 @@
 #ifndef CC_UTILS_H
 #define CC_UTILS_H
 #include "Core.h"
-/* Implements various utility functions.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Provides various utility functions
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 struct Bitmap;
diff --git a/src/Vectors.h b/src/Vectors.h
index 399a00ae3..4638a2354 100644
--- a/src/Vectors.h
+++ b/src/Vectors.h
@@ -2,9 +2,10 @@
 #define CC_VECTORS_H
 #include "Core.h"
 #include "Constants.h"
-/* Represents 2 and 3 component vectors, and 4 x 4 matrix.
-   Frustum culling sourced from http://www.crownandcutlass.com/features/technicaldetails/frustum.html
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3
+/* 
+Represents 2 and 3 component vectors, and 4 x 4 matrix
+  Frustum culling sourced from http://www.crownandcutlass.com/features/technicaldetails/frustum.html
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 /* 2 component vector (2D vector) */
diff --git a/src/Window.h b/src/Window.h
index a696bbc5e..a37bda43e 100644
--- a/src/Window.h
+++ b/src/Window.h
@@ -1,8 +1,9 @@
 #ifndef CC_WINDOW_H
 #define CC_WINDOW_H
 #include "Core.h"
-/* Abstracts creating and managing the native window.
-   Copyright 2014-2021 ClassiCube | Licensed under BSD-3 | Based on OpenTK code
+/* 
+Abstracts interaction with a windowing system (creating window, moving cursor, etc)
+Copyright 2014-2022 ClassiCube | Licensed under BSD-3
 */
 
 /*