diff --git a/demo1.cpp b/demo1.cpp
index 82ba7bd..aaa1d4f 100644
--- a/demo1.cpp
+++ b/demo1.cpp
@@ -1,5 +1,8 @@
 /**
-  WIP raycasting demo for Pokitto.
+  Raycasting demo 1 for Pokitto.
+
+  This demo is a showoff of various features (movement, textures, sprites, fog,
+  ...) , but has low FPS.
 
   Don't forget to compile with -O3!
 
@@ -686,7 +689,8 @@ Unit ceilingHeightAt(int16_t x, int16_t y)
 }
 
 /**
-  Function for drawing a single pixel (like fragment shader).
+  Function for drawing a single pixel (like fragment shader). Bottleneck =>
+  should be as fast as possible.
 */
 inline void pixelFunc(PixelInfo pixel)
 {
@@ -771,7 +775,7 @@ void draw()
   }
 }
 
-bool runReleased = false;
+bool runReleased = false; // helper for detecting switching between walk/run
 
 int main()
 {
diff --git a/demo2.cpp b/demo2.cpp
index 653d4d6..c9320a3 100644
--- a/demo2.cpp
+++ b/demo2.cpp
@@ -1,5 +1,8 @@
 /**
-  WIP raycasting demo for Pokitto.
+  Raycasting demo 2 for Pokitto.
+
+  This demo shows the simple version (only 1 intersection) of raycasting. Has
+  a fairly high FPS.
 
   Don't forget to compile with -O3!
 
diff --git a/demo3.cpp b/demo3.cpp
index a7bfd3f..faf0349 100644
--- a/demo3.cpp
+++ b/demo3.cpp
@@ -1,5 +1,8 @@
 /**
-  WIP raycasting demo for Pokitto.
+  Raycasting demo 3 for Pokitto.
+
+  Minecraft-like demo, shows an interactive terrain editing and raycasting
+  without textures.
 
   Don't forget to compile with -O3!
 
@@ -25,7 +28,7 @@ Player player;
 #define JUMP_SPEED 500
 
 char floorColor = 0;
-Vector2D selectedSquare; ///< Coords of tile selected for editing.
+Vector2D selectedSquare; ///< Coords of a square selected for editing.
 
 /**
   Represents one terrain change against the implicit terrain.
@@ -38,10 +41,11 @@ public:
   int8_t mColor;
 };
 
-#define MAX_CHANGES 16
+#define MAX_CHANGES 16 ///< Maximum number of simultaneous terrain changes.
 
-Change changes[MAX_CHANGES];
+Change changes[MAX_CHANGES]; ///< Terrain change list.
 
+// helpers
 bool editReleased = false;
 bool editing = false;
 uint16_t changeIndex = 0;
@@ -51,6 +55,8 @@ int16_t editCounter = 0;
 uint8_t squareColors[SQUARE_COLORS];
 
 #define HEIGHT_PROFILE_LENGTH 256
+
+/// Used for terrain generation.
 const int8_t heightProfile[] = {
 9,9,9,10,10,10,11,11,12,13,13,14,14,14,15,15,15,16,16,16,16,16,15,15,15,14,14,
 13,13,12,11,10,10,9,9,9,8,8,8,8,8,8,7,7,7,6,5,4,4,3,3,3,3,3,3,4,5,7,8,10,11,12,
diff --git a/general.hpp b/general.hpp
index 6893a85..b470ff7 100644
--- a/general.hpp
+++ b/general.hpp
@@ -1,5 +1,9 @@
 /**
-  General definitions for Pokitto raycasting demos.
+  General definitions common for Pokitto raycasting demos.
+
+  The demos use mode 13: 1 byte per pixel = 256 colors. Bitmaps (textures,
+  sprites, ...) are also in this format (use the provided python script to
+  convert png images).
 
   author: Miloslav "drummyfish" Ciz
   license: CC0 1.0
@@ -8,7 +12,7 @@
 #ifndef RAYCAST_DEMO_GENERAL_HPP
 #define RAYCAST_DEMO_GENERAL_HPP
 
-#include "stdio.h" // for debugging raycastlibg
+//#include "stdio.h" // for debugging raycastlibg
 
 #define VERTICAL_FOV UNITS_PER_SQUARE // redefine camera vertical FOV
 
@@ -57,7 +61,7 @@ Pokitto::Core pokitto;
 
 #define SUBSAMPLED_WIDTH (SCREEN_WIDTH / SUBSAMPLE)
 
-#define TRANSPARENT_COLOR 0b00000111
+#define TRANSPARENT_COLOR 0b00000111 /// Transparent color for sprites and GUI.
 
 Unit zBuffer[SUBSAMPLED_WIDTH]; ///< 1D z-buffer for visibility determination.
 
@@ -188,6 +192,7 @@ void inline drawSprite(const unsigned char *sprite, int16_t x, int16_t y, Unit d
   }
 }
 
+/// Faster than drawSprite.
 void drawImage(const unsigned char *image, int16_t x, int16_t y)
 {
   // TODO: optimize
@@ -349,6 +354,9 @@ void initGeneral()
     zBuffer[i] = 0;  
 }
 
+/**
+  Computes an average color of given texture.
+*/
 unsigned char computeAverageColor(const unsigned char *texture)
 {
   uint32_t sumR = 0;