Reviewed modules comments

13 files changed, 140 insertions, 70 deletions

diff --git a/src/audio.c b/src/audio.c
index 3684e10a..3ddbf0ce 100644
--- a/src/audio.c
+++ b/src/audio.c
@@ -2,18 +2,22 @@
 *
 *   raylib.audio
 *
-*   Basic functions to manage Audio:
+*   This module provides basic functionality to work with audio:
 *       Manage audio device (init/close)
-*       Load and Unload audio files
+*       Load and Unload audio files (WAV, OGG, FLAC, XM, MOD)
 *       Play/Stop/Pause/Resume loaded audio
 *       Manage mixing channels
 *       Manage raw audio context
 *
-*   Uses external lib:
-*       OpenAL Soft - Audio device management lib (http://kcat.strangesoft.net/openal.html)
-*       stb_vorbis - Ogg audio files loading (http://www.nothings.org/stb_vorbis/)
-*       jar_xm - XM module file loading
-*       jar_mod - MOD audio file loading
+*   External libs:
+*       OpenAL Soft - Audio device management (http://kcat.strangesoft.net/openal.html)
+*       stb_vorbis  - OGG audio files loading (http://www.nothings.org/stb_vorbis/)
+*       jar_xm      - XM module file loading
+*       jar_mod     - MOD audio file loading
+*       dr_flac     - FLAC audio file loading
+*
+*   Module Configuration Flags:
+*       AUDIO_STANDALONE    - Use this module as standalone library (independently of raylib)
 *
 *   Many thanks to Joshua Reisenauer (github: @kd7tck) for the following additions:
 *       XM audio module support (jar_xm)
@@ -21,6 +25,7 @@
 *       Mixing channels support
 *       Raw audio context support
 *
+*
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
 *   This software is provided "as-is", without any express or implied warranty. In no event
diff --git a/src/audio.h b/src/audio.h
index 923492ca..5de8f613 100644
--- a/src/audio.h
+++ b/src/audio.h
@@ -2,18 +2,19 @@
 *
 *   raylib.audio
 *
-*   Basic functions to manage Audio:
+*   This module provides basic functionality to work with audio:
 *       Manage audio device (init/close)
-*       Load and Unload audio files
+*       Load and Unload audio files (WAV, OGG, FLAC, XM, MOD)
 *       Play/Stop/Pause/Resume loaded audio
 *       Manage mixing channels
 *       Manage raw audio context
 *
-*   Uses external lib:
-*       OpenAL Soft - Audio device management lib (http://kcat.strangesoft.net/openal.html)
-*       stb_vorbis - Ogg audio files loading (http://www.nothings.org/stb_vorbis/)
-*       jar_xm - XM module file loading
-*       jar_mod - MOD audio file loading
+*   External libs:
+*       OpenAL Soft - Audio device management (http://kcat.strangesoft.net/openal.html)
+*       stb_vorbis  - OGG audio files loading (http://www.nothings.org/stb_vorbis/)
+*       jar_xm      - XM module file loading
+*       jar_mod     - MOD audio file loading
+*       dr_flac     - FLAC audio file loading
 *
 *   Many thanks to Joshua Reisenauer (github: @kd7tck) for the following additions:
 *       XM audio module support (jar_xm)
@@ -21,6 +22,7 @@
 *       Mixing channels support
 *       Raw audio context support
 *
+*
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
 *   This software is provided "as-is", without any express or implied warranty. In no event
diff --git a/src/core.c b/src/core.c
index 8e15eb96..991dd4a0 100644
--- a/src/core.c
+++ b/src/core.c
@@ -4,24 +4,25 @@
 *
 *   Basic functions to manage windows, OpenGL context and input on multiple platforms
 *
-*   The following platforms are supported:
-*       PLATFORM_DESKTOP - Windows, Linux, Mac (OSX)
-*       PLATFORM_ANDROID - Only OpenGL ES 2.0 devices
-*       PLATFORM_RPI - Rapsberry Pi (tested on Raspbian)
-*       PLATFORM_WEB - Emscripten, HTML5
-*       Oculus Rift CV1 (with desktop mirror) - View [rlgl] module to enable it
+*   The following platforms are supported: Windows, Linux, Mac (OSX), Android, Raspberry Pi, HTML5, Oculus Rift CV1
 *
-*   On PLATFORM_DESKTOP, the external lib GLFW3 (www.glfw.com) is used to manage graphic
-*   device, OpenGL context and input on multiple operating systems (Windows, Linux, OSX).
-*
-*   On PLATFORM_ANDROID, graphic device is managed by EGL and input system by Android activity.
-*
-*   On PLATFORM_RPI, graphic device is managed by EGL and input system is coded in raw mode.
+*   External libs:
+*       GLFW3    - Manage graphic device, OpenGL context and inputs on PLATFORM_DESKTOP (Windows, Linux, OSX)
+*       raymath  - 3D math functionality (Vector3, Matrix, Quaternion)
+*       camera   - Multiple 3D camera modes (free, orbital, 1st person, 3rd person) 
+*       gestures - Gestures system for touch-ready devices (or simulated from mouse inputs)
 *
 *   Module Configuration Flags:
+*       PLATFORM_DESKTOP     - Windows, Linux, Mac (OSX)
+*       PLATFORM_ANDROID     - Android (only OpenGL ES 2.0 devices), graphic device is managed by EGL and input system by Android activity.
+*       PLATFORM_RPI         - Rapsberry Pi (tested on Raspbian), graphic device is managed by EGL and input system is coded in raw mode.
+*       PLATFORM_WEB         - HTML5 (using emscripten compiler)
 *
 *       RL_LOAD_DEFAULT_FONT - Use external module functions to load default raylib font (module: text)
 *
+*   NOTE: Oculus Rift CV1 requires PLATFORM_DESKTOP for render mirror - View [rlgl] module to enable it
+*
+*
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
 *   This software is provided "as-is", without any express or implied warranty. In no event
diff --git a/src/external/stb_image.h b/src/external/stb_image.h
index ce87646d..5572a880 100644
--- a/src/external/stb_image.h
+++ b/src/external/stb_image.h
@@ -390,7 +390,7 @@ publish, and distribute this file as you see fit.
 
 
 #define STBI_NO_HDR		// RaySan: not required by raylib
-#define STBI_NO_SIMD    // RaySan: issues when compiling with GCC 4.7.2
+//#define STBI_NO_SIMD    // RaySan: issues when compiling with GCC 4.7.2
 
 #ifndef STBI_NO_STDIO
 #include <stdio.h>
@@ -398,7 +398,7 @@ publish, and distribute this file as you see fit.
 
 // NOTE: Added to work with raylib on Android
 #if defined(PLATFORM_ANDROID)
-    #include "utils.h"  // Android fopen function map
+    #include "utils.h"  // RaySan: Android fopen function map
 #endif
 
 #define STBI_VERSION 1
diff --git a/src/models.c b/src/models.c
index b7e36b8a..4275f89e 100644
--- a/src/models.c
+++ b/src/models.c
@@ -4,6 +4,12 @@
 *
 *   Basic functions to draw 3d shapes and load/draw 3d models (.OBJ)
 *
+*   External libs:
+*       rlgl     - raylib OpenGL abstraction layer
+*
+*   Module Configuration Flags:
+*       ...
+*
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
 *   This software is provided "as-is", without any express or implied warranty. In no event
@@ -34,8 +40,7 @@
 #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"        // Matrix data type and Matrix functions
+#include "rlgl.h"           // raylib OpenGL abstraction layer to OpenGL 1.1, 2.1, 3.3+ or ES2
 
 //----------------------------------------------------------------------------------
 // Defines and Macros
diff --git a/src/raylib.h b/src/raylib.h
index 2e3112cf..ef393f63 100644
--- a/src/raylib.h
+++ b/src/raylib.h
@@ -6,37 +6,39 @@
 *
 *   Features:
 *     Library written in plain C code (C99)
-*     Uses C# PascalCase/camelCase notation
+*     Uses PascalCase/camelCase notation
 *     Hardware accelerated with OpenGL (1.1, 2.1, 3.3 or ES 2.0)
 *     Unique OpenGL abstraction layer (usable as standalone module): [rlgl]
 *     Powerful fonts module with SpriteFonts support (XNA bitmap fonts, AngelCode fonts, TTF)
 *     Multiple textures support, including compressed formats and mipmaps generation
 *     Basic 3d support for Shapes, Models, Billboards, Heightmaps and Cubicmaps
 *     Materials (diffuse, normal, specular) and Lighting (point, directional, spot) support
-*     Powerful math module for Vector, Matrix and Quaternion operations [raymath]
-*     Audio loading and playing with streaming support and mixing channels (WAV, OGG, XM, MOD)
+*     Powerful math module for Vector, Matrix and Quaternion operations: [raymath]
+*     Audio loading and playing with streaming support and mixing channels [audio]
 *     VR stereo rendering support with configurable HMD device parameters
 *     Multiple platforms support: Windows, Linux, Mac, Android, Raspberry Pi, HTML5 and Oculus Rift CV1
 *     Custom color palette for fancy visuals on raywhite background
 *     Minimal external dependencies (GLFW3, OpenGL, OpenAL)
+*     Complete binding for LUA [rlua]
 *
-*   Used external libs:
-*     GLFW3 (www.glfw.org) for window/context management and input
-*     GLAD for OpenGL extensions loading (3.3 Core profile, only PLATFORM_DESKTOP)
-*     stb_image (Sean Barret) for images loading (JPEG, PNG, BMP, TGA, PSD, GIF, HDR, PIC)
-*     stb_image_write (Sean Barret) for image writting (PNG)
-*     stb_vorbis (Sean Barret) for ogg audio loading
-*     stb_truetype (Sean Barret) for ttf fonts loading
-*     jar_xm (Joshua Reisenauer) for XM audio module loading
-*     jar_mod (Joshua Reisenauer) for MOD audio module loading
-*     OpenAL Soft for audio device/context management
-*     tinfl for data decompression (DEFLATE algorithm)
+*   External libs:
+*     GLFW3 (www.glfw.org) for window/context management and input [core]
+*     GLAD for OpenGL extensions loading (3.3 Core profile, only PLATFORM_DESKTOP) [rlgl]
+*     stb_image (Sean Barret) for images loading (JPEG, PNG, BMP, TGA) [textures]
+*     stb_image_write (Sean Barret) for image writting (PNG) [utils]
+*     stb_truetype (Sean Barret) for ttf fonts loading [text]
+*     stb_vorbis (Sean Barret) for ogg audio loading [audio]
+*     jar_xm (Joshua Reisenauer) for XM audio module loading [audio]
+*     jar_mod (Joshua Reisenauer) for MOD audio module loading [audio]
+*     dr_flac (David Reid) for FLAC audio file loading [audio]
+*     OpenAL Soft for audio device/context management [audio]
+*     tinfl for data decompression (DEFLATE algorithm) [utils]
 *
 *   Some design decisions:
 *     32bit Colors - All defined color are always RGBA (struct Color is 4 byte)
-*     One custom default font is loaded automatically when InitWindow()
+*     One custom default font could be loaded automatically when InitWindow() [core]
 *     If using OpenGL 3.3 or ES2, several vertex buffers (VAO/VBO) are created to manage lines-triangles-quads
-*     If using OpenGL 3.3 or ES2, two default shaders are loaded automatically (internally defined)
+*     If using OpenGL 3.3 or ES2, two default shaders could be loaded automatically (internally defined)
 *
 *   -- LICENSE --
 *
diff --git a/src/rlgl.c b/src/rlgl.c
index d3bba07b..28dc5171 100644
--- a/src/rlgl.c
+++ b/src/rlgl.c
@@ -2,11 +2,30 @@
 *
 *   rlgl - raylib OpenGL abstraction layer
 *
-*   raylib now uses OpenGL 1.1 style functions (rlVertex) that are mapped to selected OpenGL version:
-*       OpenGL 1.1  - Direct map rl* -> gl*
-*       OpenGL 2.1  - Vertex data is stored in VBOs, call rlglDraw() to render
-*       OpenGL 3.3  - Vertex data is stored in VAOs, call rlglDraw() to render
-*       OpenGL ES 2 - Vertex data is stored in VBOs or VAOs (when available), call rlglDraw() to render
+*   rlgl allows usage of OpenGL 1.1 style functions (rlVertex) that are internally mapped to 
+*   selected OpenGL version (1.1, 2.1, 3.3 Core, ES 2.0). 
+*
+*   When chosing an OpenGL version greater than OpenGL 1.1, rlgl stores vertex data on internal 
+*   VBO buffers (and VAOs if available). It requires calling 3 functions:
+*       rlglInit()  - Initialize internal buffers and auxiliar resources
+*       rlglDraw()  - Process internal buffers and send required draw calls
+*       rlglClose() - De-initialize internal buffers data and other auxiliar resources
+*
+*   External libs:
+*       raymath     - 3D math functionality (Vector3, Matrix, Quaternion)
+*       GLAD        - OpenGL extensions loading (OpenGL 3.3 Core only)
+*
+*   Module Configuration Flags:
+*       GRAPHICS_API_OPENGL_11  - Use OpenGL 1.1 backend
+*       GRAPHICS_API_OPENGL_21  - Use OpenGL 2.1 backend
+*       GRAPHICS_API_OPENGL_33  - Use OpenGL 3.3 Core profile backend
+*       GRAPHICS_API_OPENGL_ES2 - Use OpenGL ES 2.0 backend
+*
+*       RLGL_STANDALONE             - Use rlgl as standalone library (no raylib dependency)
+*       RLGL_NO_STANDARD_SHADER     - Avoid standard shader (shader_standard.h) inclusion
+*       RLGL_NO_DISTORTION_SHADER   - Avoid stereo rendering distortion sahder (shader_distortion.h) inclusion
+*       RLGL_OCULUS_SUPPORT         - Enable Oculus Rift CV1 functionality
+*
 *
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
diff --git a/src/rlgl.h b/src/rlgl.h
index 78ea6727..e4d40714 100644
--- a/src/rlgl.h
+++ b/src/rlgl.h
@@ -2,11 +2,27 @@
 *
 *   rlgl - raylib OpenGL abstraction layer
 *
-*   raylib now uses OpenGL 1.1 style functions (rlVertex) that are mapped to selected OpenGL version:
-*       OpenGL 1.1  - Direct map rl* -> gl*
-*       OpenGL 2.1  - Vertex data is stored in VBOs, call rlglDraw() to render
-*       OpenGL 3.3  - Vertex data is stored in VAOs, call rlglDraw() to render
-*       OpenGL ES 2 - Vertex data is stored in VBOs or VAOs (when available), call rlglDraw() to render
+*   rlgl allows usage of OpenGL 1.1 style functions (rlVertex) that are internally mapped to 
+*   selected OpenGL version (1.1, 2.1, 3.3 Core, ES 2.0). 
+*
+*   When chosing an OpenGL version greater than OpenGL 1.1, rlgl stores vertex data on internal 
+*   VBO buffers (and VAOs if available). It requires calling 3 functions:
+*       rlglInit()  - Initialize internal buffers and auxiliar resources
+*       rlglDraw()  - Process internal buffers and send required draw calls
+*       rlglClose() - De-initialize internal buffers data and other auxiliar resources
+*
+*   External libs:
+*       raymath     - 3D math functionality (Vector3, Matrix, Quaternion)
+*       GLAD        - OpenGL extensions loading (OpenGL 3.3 Core only)
+*
+*   Module Configuration Flags:
+*       GRAPHICS_API_OPENGL_11  - Use OpenGL 1.1 backend
+*       GRAPHICS_API_OPENGL_21  - Use OpenGL 2.1 backend
+*       GRAPHICS_API_OPENGL_33  - Use OpenGL 3.3 Core profile backend
+*       GRAPHICS_API_OPENGL_ES2 - Use OpenGL ES 2.0 backend
+*
+*       RLGL_STANDALONE             - Use rlgl as standalone library (no raylib dependency)
+*
 *
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
diff --git a/src/shapes.c b/src/shapes.c
index 79cf567a..70aad59a 100644
--- a/src/shapes.c
+++ b/src/shapes.c
@@ -4,6 +4,12 @@
 *
 *   Basic functions to draw 2d Shapes and check collisions
 *
+*   External libs:
+*       rlgl     - raylib OpenGL abstraction layer
+*
+*   Module Configuration Flags:
+*       ...
+*
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
 *   This software is provided "as-is", without any express or implied warranty. In no event
@@ -25,11 +31,11 @@
 
 #include "raylib.h"
 
+#include "rlgl.h"       // raylib OpenGL abstraction layer to OpenGL 1.1, 2.1, 3.3+ or ES2
+
 #include <stdlib.h>     // Required for: abs()
 #include <math.h>       // Required for: sinf(), cosf(), sqrtf()
 
-#include "rlgl.h"       // raylib OpenGL abstraction layer to OpenGL 1.1, 3.3+ or ES2
-
 //----------------------------------------------------------------------------------
 // Defines and Macros
 //----------------------------------------------------------------------------------
diff --git a/src/text.c b/src/text.c
index 72d273d4..d752f1cb 100644
--- a/src/text.c
+++ b/src/text.c
@@ -4,6 +4,12 @@
 *
 *   Basic functions to load SpriteFonts and draw Text
 *
+*   External libs:
+*       stb_truetype - Load TTF file and rasterize characters data
+*
+*   Module Configuration Flags:
+*       ...
+*
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
 *   This software is provided "as-is", without any express or implied warranty. In no event
@@ -33,7 +39,7 @@
 #include "utils.h"          // Required for: GetExtension(), GetNextPOT()
 
 // Following libs are used on LoadTTF()
-//#define STBTT_STATIC
+#define STBTT_STATIC        // Define stb_truetype functions static to this module
 #define STB_TRUETYPE_IMPLEMENTATION
 #include "external/stb_truetype.h"      // Required for: stbtt_BakeFontBitmap()
 
diff --git a/src/textures.c b/src/textures.c
index 5354a74f..af59d035 100644
--- a/src/textures.c
+++ b/src/textures.c
@@ -4,9 +4,13 @@
 *
 *   Basic functions to load and draw Textures (2d)
 *
-*   Uses external lib:
-*       stb_image - Multiple formats image loading (JPEG, PNG, BMP, TGA, PSD, GIF, PIC)
-*                   NOTE: stb_image has been slightly modified, original library: https://github.com/nothings/stb
+*   External libs:
+*       stb_image        - Multiple image formats loading (JPEG, PNG, BMP, TGA, PSD, GIF, PIC)
+*                          NOTE: stb_image has been slightly modified to support Android platform.
+*       stb_image_resize - Multiple image resize algorythms
+*
+*   Module Configuration Flags:
+*       ...
 *
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
diff --git a/src/utils.c b/src/utils.c
index b96e2c70..640c5720 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -2,12 +2,16 @@
 *
 *   raylib.utils
 *
-*   Utils Functions Definitions
+*   Some utility functions
 *
-*   Uses external libs:
-*       tinfl - zlib DEFLATE algorithm decompression lib
+*   External libs:
+*       tinfl           - zlib DEFLATE algorithm decompression
 *       stb_image_write - PNG writting functions
 *
+*   Module Configuration Flags:
+*       DO_NOT_TRACE_DEBUG_MSGS - Avoid showing DEBUG TraceLog() messages
+*
+*
 *   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
 *   This software is provided "as-is", without any express or implied warranty. In no event
@@ -46,7 +50,9 @@
 #endif
 
 #include "external/tinfl.c"         // Required for: tinfl_decompress_mem_to_mem()
-                                    // NOTE: Deflate algorythm data decompression
+                                    // NOTE: DEFLATE algorythm data decompression
+
+#define DO_NOT_TRACE_DEBUG_MSGS     // Avoid DEBUG messages tracing
 
 //----------------------------------------------------------------------------------
 // Global Variables Definition
diff --git a/src/utils.h b/src/utils.h
index 899cf583..045b0692 100644
--- a/src/utils.h
+++ b/src/utils.h
@@ -2,9 +2,9 @@
 *
 *   raylib.utils
 *
-*   Some utility functions: rRES files data decompression
+*   Some utility functions
 *
-*   Copyright (c) 2014 Ramon Santamaria (@raysan5)
+*   Copyright (c) 2014-2016 Ramon Santamaria (@raysan5)
 *
 *   This software is provided "as-is", without any express or implied warranty. In no event
 *   will the authors be held liable for any damages arising from the use of this software.
@@ -34,8 +34,6 @@
 //----------------------------------------------------------------------------------
 // Some basic Defines
 //----------------------------------------------------------------------------------
-#define DO_NOT_TRACE_DEBUG_MSGS   // Use this define to avoid DEBUG tracing
-
 #if defined(PLATFORM_ANDROID)
     #define fopen(name, mode) android_fopen(name, mode) 
 #endif