Review heades usage

This is a first step toward a bigger project. Some modules could be
ported to header-only to be used as standalone.

8 files changed, 54 insertions, 52 deletions

diff --git a/src/audio.c b/src/audio.c
index 0c61c0fa..a884303c 100644
--- a/src/audio.c
+++ b/src/audio.c
@@ -37,24 +37,24 @@
 
 #include "AL/al.h"          // OpenAL basic header
 #include "AL/alc.h"         // OpenAL context header (like OpenGL, OpenAL requires a context to work)
-#include "AL/alext.h"       // extensions for other format types
+#include "AL/alext.h"       // OpenAL extensions for other format types
 
-#include <stdlib.h>         // Declares malloc() and free() for memory management
-#include <string.h>         // Required for strcmp()
-#include <stdio.h>          // Used for .WAV loading
+#include <stdlib.h>         // Required for: malloc(), free()
+#include <string.h>         // Required for: strcmp(), strncmp()
+#include <stdio.h>          // Required for: FILE, fopen(), fclose(), fread()
 
 #if defined(AUDIO_STANDALONE)
-    #include <stdarg.h>     // Used for functions with variable number of parameters (TraceLog())
+    #include <stdarg.h>     // Required for: va_list, va_start(), vfprintf(), va_end()
 #else
-    #include "utils.h"      // rRES data decompression utility function
-                            // NOTE: Includes Android fopen function map
+    #include "utils.h"      // Required for: DecompressData()
+                            // NOTE: Includes Android fopen() function map
 #endif
 
 //#define STB_VORBIS_HEADER_ONLY
 #include "stb_vorbis.h"     // OGG loading functions
 
 #define JAR_XM_IMPLEMENTATION
-#include "jar_xm.h"         // For playing .xm files
+#include "jar_xm.h"         // XM loading functions
 
 //----------------------------------------------------------------------------------
 // Defines and Macros
diff --git a/src/models.c b/src/models.c
index 962a6470..15565c98 100644
--- a/src/models.c
+++ b/src/models.c
@@ -26,16 +26,16 @@
 #include "raylib.h"
 
 #if defined(PLATFORM_ANDROID)
-    #include "utils.h"  // Android fopen function map
+    #include "utils.h"      // Android fopen function map
 #endif
 
-#include <stdio.h>      // Standard input/output functions, used to read model files data
-#include <stdlib.h>     // Declares malloc() and free() for memory management
-#include <string.h>     // Required for strcmp()
-#include <math.h>       // Used for sin, cos, tan
+#include <stdio.h>          // Required for: FILE, fopen(), fclose(), fscanf(), feof(), rewind(), fgets()
+#include <stdlib.h>         // Required for: malloc(), free()
+#include <string.h>         // Required for: strcmp()
+#include <math.h>           // Required for: sin(), cos()
 
-#include "rlgl.h"       // raylib OpenGL abstraction layer to OpenGL 1.1, 3.3+ or ES2
-#include "raymath.h"    // Required for data type Matrix and Matrix functions
+#include "rlgl.h"           // raylib OpenGL abstraction layer to OpenGL 1.1, 3.3+ or ES2
+#include "raymath.h"        // Matrix data type and Matrix functions
 
 //----------------------------------------------------------------------------------
 // Defines and Macros
@@ -605,7 +605,7 @@ Model LoadModel(const char *fileName)
     
     // TODO: Initialize default data for model in case loading fails, maybe a cube?
 
-    if (strcmp(GetExtension(fileName),"obj") == 0) model.mesh = LoadOBJ(fileName);
+    if (strcmp(GetExtension(fileName), "obj") == 0) model.mesh = LoadOBJ(fileName);
     else TraceLog(WARNING, "[%s] Model extension not recognized, it can't be loaded", fileName);
 
     if (model.mesh.vertexCount == 0) TraceLog(WARNING, "Model could not be loaded");
@@ -764,7 +764,7 @@ Material LoadMaterial(const char *fileName)
 {
     Material material = { 0 };
     
-    if (strcmp(GetExtension(fileName),"mtl") == 0) material = LoadMTL(fileName);
+    if (strcmp(GetExtension(fileName), "mtl") == 0) material = LoadMTL(fileName);
     else TraceLog(WARNING, "[%s] Material extension not recognized, it can't be loaded", fileName);
     
     return material;
diff --git a/src/rlgl.c b/src/rlgl.c
index aa536e2a..cca48ba2 100644
--- a/src/rlgl.c
+++ b/src/rlgl.c
@@ -28,41 +28,41 @@
 
 #include "rlgl.h"
 
-#include <stdio.h>          // Standard input / output lib
-#include <stdlib.h>         // Declares malloc() and free() for memory management, rand()
-#include <string.h>         // Declares strcmp(), strlen(), strtok()
+#include <stdio.h>                  // Standard input / output lib
+#include <stdlib.h>                 // Required for: malloc(), free(), rand()
+#include <string.h>                 // Required for: strcmp(), strlen(), strtok()
 
 #ifndef RLGL_STANDALONE
-    #include "raymath.h"    // Required for Vector3 and Matrix functions
+    #include "raymath.h"            // Required for Vector3 and Matrix functions
 #endif
 
 #if defined(GRAPHICS_API_OPENGL_11)
-    #ifdef __APPLE__                // OpenGL include for OSX
-        #include <OpenGL/gl.h>
+    #ifdef __APPLE__                
+        #include <OpenGL/gl.h>      // OpenGL 1.1 library for OSX
     #else
-        #include <GL/gl.h>          // Basic OpenGL include
+        #include <GL/gl.h>          // OpenGL 1.1 library
     #endif
 #endif
 
 #if defined(GRAPHICS_API_OPENGL_33)
-    #ifdef __APPLE__                // OpenGL include for OSX
-        #include <OpenGL/gl3.h>
+    #ifdef __APPLE__ 
+        #include <OpenGL/gl3.h>     // OpenGL 3 library for OSX
     #else
         //#define GLEW_STATIC
         //#include <GL/glew.h>        // GLEW header, includes OpenGL headers
-        #include "glad.h"         // glad header, includes OpenGL headers
+        #include "glad.h"           // GLAD library, includes OpenGL headers
     #endif
 #endif
 
 #if defined(GRAPHICS_API_OPENGL_ES2)
-    #include <EGL/egl.h>
-    #include <GLES2/gl2.h>
-    #include <GLES2/gl2ext.h>
+    #include <EGL/egl.h>            // EGL library
+    #include <GLES2/gl2.h>          // OpenGL ES 2.0 library
+    #include <GLES2/gl2ext.h>       // OpenGL ES 2.0 extensions library
 #endif
 
 #if defined(RLGL_STANDALONE)
-    #include <stdarg.h>         // Used for functions with variable number of parameters (TraceLog())
-#endif
+    #include <stdarg.h>             // Required for: va_list, va_start(), vfprintf(), va_end()
+#endif                              // NOTE: Used on TraceLog()
 
 //----------------------------------------------------------------------------------
 // Defines and Macros
diff --git a/src/rlgl.h b/src/rlgl.h
index e8e754b4..00482d2e 100644
--- a/src/rlgl.h
+++ b/src/rlgl.h
@@ -32,15 +32,15 @@
 //#define RLGL_STANDALONE       // NOTE: To use rlgl as standalone lib, just uncomment this line
 
 #ifndef RLGL_STANDALONE
-    #include "raylib.h"         // Required for typedef(s): Model, Shader, Texture2D
-    #include "utils.h"          // Required for function TraceLog()
+    #include "raylib.h"         // Required for: Model, Shader, Texture2D
+    #include "utils.h"          // Required for: TraceLog()
 #endif
 
 #ifdef RLGL_STANDALONE
     #define RAYMATH_STANDALONE
 #endif
 
-#include "raymath.h"            // Required for types: Vector3, Matrix
+#include "raymath.h"            // Required for: Vector3, Matrix
 
 // Select desired OpenGL version
 // NOTE: Those preprocessor defines are only used on rlgl module,
diff --git a/src/text.c b/src/text.c
index 7bb06f44..cef0ebcb 100644
--- a/src/text.c
+++ b/src/text.c
@@ -25,16 +25,16 @@
 
 #include "raylib.h"
 
-#include <stdlib.h>       // Declares malloc() and free() for memory management
-#include <string.h>       // String management functions (just strlen() is used)
-#include <stdarg.h>       // Used for functions with variable number of parameters (FormatText())
-#include <stdio.h>        // Standard input / output lib
+#include <stdlib.h>         // Required for: malloc(), free()
+#include <string.h>         // Required for: strlen()
+#include <stdarg.h>         // Required for: va_list, va_start(), vfprintf(), va_end()
+#include <stdio.h>          // Required for: FILE, fopen(), fclose(), fscanf(), feof(), rewind(), fgets()
 
-#include "utils.h"        // Required for function GetExtension()
+#include "utils.h"          // Required for: GetExtension()
 
 // Following libs are used on LoadTTF()
 #define STB_TRUETYPE_IMPLEMENTATION
-#include "stb_truetype.h"
+#include "stb_truetype.h"   // Required for: stbtt_BakeFontBitmap()
 
 // Rectangle packing functions (not used at the moment)
 //#define STB_RECT_PACK_IMPLEMENTATION
diff --git a/src/textures.c b/src/textures.c
index 8c59f3f2..432d3426 100644
--- a/src/textures.c
+++ b/src/textures.c
@@ -29,8 +29,8 @@
 
 #include "raylib.h"
 
-#include <stdlib.h>             // Declares malloc() and free() for memory management
-#include <string.h>             // Required for strcmp(), strrchr(), strncmp()
+#include <stdlib.h>             // Required for: malloc(), free()
+#include <string.h>             // Required for: strcmp(), strrchr(), strncmp()
 
 #include "rlgl.h"               // raylib OpenGL abstraction layer to OpenGL 1.1, 3.3 or ES2
                                 // Required: rlglLoadTexture() rlDeleteTextures(), 
@@ -40,10 +40,12 @@
                                 // NOTE: Includes Android fopen function map
 
 #define STB_IMAGE_IMPLEMENTATION
-#include "stb_image.h"          // Used to read image data (multiple formats support)
+#include "stb_image.h"          // Required for: stbi_load()
+                                // NOTE: Used to read image data (multiple formats support)
 
 #define STB_IMAGE_RESIZE_IMPLEMENTATION
-#include "stb_image_resize.h"   // Used on image scaling function: ImageResize()
+#include "stb_image_resize.h"   // Required for: stbir_resize_uint8() 
+                                // NOTE: Used for image scaling on ImageResize()
 
 //----------------------------------------------------------------------------------
 // Defines and Macros
diff --git a/src/utils.c b/src/utils.c
index f0ccf3e2..97561ee6 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -35,14 +35,14 @@
     #include <android/asset_manager.h>
 #endif
 
-#include <stdlib.h>             // malloc(), free()
-#include <stdio.h>              // printf(), fprintf()
-#include <stdarg.h>             // Used for functions with variable number of parameters (TraceLog())
-//#include <string.h>           // String management functions: strlen(), strrchr(), strcmp()
+#include <stdlib.h>                 // Required for: malloc(), free()
+#include <stdio.h>                  // Required for: fopen(), fclose(), fputc(), fwrite(), printf(), fprintf(), funopen()
+#include <stdarg.h>                 // Required for: va_list, va_start(), vfprintf(), va_end()
+//#include <string.h>               // Required for: strlen(), strrchr(), strcmp()
 
 #if defined(PLATFORM_DESKTOP) || defined(PLATFORM_RPI)
     #define STB_IMAGE_WRITE_IMPLEMENTATION
-    #include "stb_image_write.h"    // Create PNG file
+    #include "stb_image_write.h"    // Required for: stbi_write_png()
 #endif
 
 #include "tinfl.c"
diff --git a/src/utils.h b/src/utils.h
index 77909ba6..899cf583 100644
--- a/src/utils.h
+++ b/src/utils.h
@@ -27,8 +27,8 @@
 #define UTILS_H
 
 #if defined(PLATFORM_ANDROID)
-    #include <stdio.h>                      // Defines FILE struct
-    #include <android/asset_manager.h>      // defines AAssetManager struct
+    #include <stdio.h>                      // Required for: FILE
+    #include <android/asset_manager.h>      // Required for: AAssetManager
 #endif
 
 //----------------------------------------------------------------------------------