--- a/include/raytracer.h	Thu May 15 19:15:57 2008 +0200
+++ b/include/raytracer.h	Mon May 19 22:59:04 2008 +0200
@@ -42,26 +42,49 @@
  */
 class Raytracer
 {
-	Container *top;
-	Sampler *sampler;
-	Camera *camera;
-	vector<Light*> lights;
-	Colour bg_colour;
+	Container *top;    /**< container with shapes */
+	Sampler *sampler;  /**< active sampler */
+	Camera *camera;    /**< active camera */
+	vector<Light*> lights; /**< array of lights in the scene */
+	Colour bg_colour;  /**< background colour */
+
+	/* ambient occlussion parameters */
 	Float ao_distance, ao_angle;
 	int ao_samples;
-	int num_threads;
-	int max_depth;
-	bool use_packets;
 
+	int num_threads;  /**< number of threads to use for rendering */
+	int max_depth;    /**< maximum depth of recursion */
+	bool use_packets; /**< allow ray packet tracing */
+
+	/* private helper variables */
 	Sample *sample_queue;
 	int sample_queue_pos, sample_queue_size, sample_queue_count;
 	bool end_of_samples;
 	pthread_mutex_t sample_queue_mutex, sampler_mutex;
 	pthread_cond_t sample_queue_cond, worker_ready_cond;
 
+	/**
+	 * Hammersley spherical point distribution function
+	 * http://www.cse.cuhk.edu.hk/~ttwong/papers/udpoint/udpoints.html
+	 * @param[in] i   sample index
+	 * @param[in] n   number of samples
+	 * @param[in] extent   angle of dispersion
+	 * @param[in] normal   central direction vector
+	 */
 	Vector SphereDistribute(int i, int n, Float extent, const Vector &normal);
+
+	/**
+	 * shader implementing Phong lighting model
+	 * @param[in] P    point of intersection
+	 * @param[in] N    normal in intersect. point
+	 * @param[in] R    direction of reflected ray
+	 * @param[in] V    direction to the viewer
+	 * @return colour of the surface
+	 */
 	Colour PhongShader(const Shape *shape,
 		const Vector &P, const Vector &N, const Vector &V);
+
+	/** light scattering function */
 	void lightScatter(const Ray &ray, const Shape *shape, int depth,
 		const Vector &P, const Vector &normal, bool from_inside, Colour &col);
 
@@ -71,6 +94,7 @@
 	void raytracePacket(RayPacket &rays, Colour *results);
 #endif
 
+	/** main function of the ray tracing worker */
 	NORETURN static void *raytrace_worker(void *d);
 
 public:
@@ -90,21 +114,40 @@
 		pthread_cond_destroy (&worker_ready_cond);
 	}
 
+	/** start the rendering process */
 	void render();
+
+	/** ray trace one ray */
 	Colour raytrace(Ray &ray, int depth, const Shape *origin_shape);
+
+	/** add shape to container */
 	void addShape(Shape *shape) { top->addShape(shape); };
+
+	/** add light to scene */
 	void addLight(Light *light) { lights.push_back(light); };
+
+	/** set active sampler */
 	void setSampler(Sampler *sampl) { sampler = sampl; };
 	Sampler *&getSampler() { return sampler; };
+
+	/** set active camera */
 	void setCamera(Camera *cam) { camera = cam; };
 	Camera *&getCamera() { return camera; };
+
+	/** set active container */
 	void setTop(Container *atop) { top = atop; };
 	Container *&getTop() { return top; };
 
+	/** set background colour */
 	void setBgColour(const Colour &bg) { bg_colour = bg; };
+
+	/** set maximum depth of recursion */
 	void setMaxDepth(int newdepth) { max_depth = newdepth; };
 
+	/** set ambient occlusion parameters */
 	void ambientOcclusion(int samples, Float distance, Float angle);
+
+	/** set number of threads to use for rendering */
 	void setThreads(int num) { num_threads = num; };
 };