From d3f8f6956f2056018ab814e4a04d1079c6d04de0 Mon Sep 17 00:00:00 2001
From: Simon Wiesend <117300309+smnws@users.noreply.github.com>
Date: Sun, 23 Nov 2025 17:11:22 +0100
Subject: [PATCH] add some comments

---
 imageInput.c | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/imageInput.c b/imageInput.c
index 5408f64..f062049 100644
--- a/imageInput.c
+++ b/imageInput.c
@@ -21,6 +21,7 @@ static ImageError parseImageFile(FILE *file, GrayScaleImageSeries *series);
 
 GrayScaleImageSeries *readImages(const char *path)
 {
+    // It's very important to call calloc here because otherwise clearSeries() might try to free random memory
     GrayScaleImageSeries *series = calloc(1, sizeof(GrayScaleImageSeries));
     if (series == NULL)
     {
@@ -28,17 +29,19 @@ GrayScaleImageSeries *readImages(const char *path)
     }
 
     FILE *file = fopen(path, "rb");
+    // If fopen() failed
     if (file == NULL)
     {
         clearSeries(series);
         series = NULL;
-        return NULL; // fopen failed
+        return NULL;
     }
 
+    // Try to parse the whole file. If anything fails memory is gets freed
     if (parseImageFile(file, series))
     {
         clearSeries(series);
-        series = NULL;
+        series = NULL; // Return NULL after the file is properly closed 
     }
 
     fclose(file);
@@ -52,28 +55,29 @@ static ImageError parseImageFile(FILE *file, GrayScaleImageSeries *series)
         return IMG_ERR; // header check failed
     }
 
-    unsigned short number, width, height;
-    if (readPictureParams(&number, &width, &height, file))
+    unsigned short imgCNT, width, height;
+    if (readPictureParams(&imgCNT, &width, &height, file))
     {
         return IMG_ERR; // read failed
     }
     size_t pixels = width * height;
 
-    // now setup the image series
-    series->images = calloc(number, sizeof(GrayScaleImage));
+    // The images contain more pointers, definitely use calloc here
+    series->images = calloc(imgCNT, sizeof(GrayScaleImage));
     if (series->images == NULL)
     {
         return IMG_ERR;
     }
 
-    series->labels = malloc(number * sizeof(unsigned char));
+    series->labels = malloc(imgCNT * sizeof(unsigned char));
     if (series->labels == NULL)
     {
         return IMG_ERR;
     }
 
-    series->count = number;
-    for (size_t imageIdx = 0; imageIdx < number; imageIdx++)
+    series->count = imgCNT;
+    // Read every image and it's label
+    for (size_t imageIdx = 0; imageIdx < imgCNT; imageIdx++)
     {
         GrayScaleImage *curImage = &series->images[imageIdx];
 
@@ -99,26 +103,30 @@ static ImageError checkHeader(FILE *file)
     size_t len = strlen(FILE_HEADER_STRING);
     char headerBuf[len + 1];
     size_t charsRead = fread(headerBuf, 1, len, file);
+    // Check if the file is to short
     if (charsRead < len)
     {
         return IMG_ERR_READ;
     }
-    headerBuf[len] = '\0';
+    headerBuf[len] = '\0'; // Terminate string
     return strcmp(headerBuf, FILE_HEADER_STRING) == 0 ? IMG_SUCCESS : IMG_ERR_INVALID_HEADER;
 }
 
 static ImageError readPictureParams(unsigned short *number, unsigned short *width, unsigned short *height, FILE *file)
 {
+    // number of images
     if (1 != fread(number, sizeof(unsigned short), 1, file))
     {
         return IMG_ERR_READ;
     }
 
+    // image width
     if (1 != fread(width, sizeof(unsigned short), 1, file))
     {
         return IMG_ERR_READ;
     }
 
+    // height
     if (1 != fread(height, sizeof(unsigned short), 1, file))
     {
         return IMG_ERR_READ;
@@ -127,6 +135,7 @@ static ImageError readPictureParams(unsigned short *number, unsigned short *widt
     return IMG_SUCCESS;
 }
 
+// Read 1 image and it's label
 static ImageError readImage(size_t numPixels, GrayScalePixelType *pixelBuffer, unsigned char *label, FILE *file)
 {
     if (numPixels > fread(pixelBuffer, sizeof(GrayScalePixelType), numPixels, file))
@@ -142,7 +151,7 @@ static ImageError readImage(size_t numPixels, GrayScalePixelType *pixelBuffer, u
     return IMG_SUCCESS;
 }
 
-// frees memory for each image buffer, image, label and finally series
+// Frees memory for each image buffer, image, label and finally series
 void clearSeries(GrayScaleImageSeries *series)
 {
     if (series)