--- a/include/shapes.h	Thu May 15 19:15:57 2008 +0200
+++ b/include/shapes.h	Mon May 19 22:59:04 2008 +0200
@@ -44,7 +44,7 @@
 #endif
 
 /**
- * shape
+ * abstract shape class
  */
 class Shape
 {
@@ -54,9 +54,18 @@
 	Shape() {};
 	virtual ~Shape() {};
 
-	// first intersection point
+	/**
+	 * intersect ray with sphere
+	 * @param[in] ray	the ray
+	 * @param[in] dist	maximum allowed distance of intersection
+	 * @param[out] dist	distance of the intersection if found, unchanged otherwise
+	 * @return true if ray intersects the sphere
+	 */
 	virtual bool intersect(const Ray &ray, Float &dist) const = 0;
 
+	/**
+	 * same as intersect, but for ray packets
+	 */
 #ifndef NO_SIMD
 	virtual mfloat4 intersect_packet(const RayPacket &rays, mfloat4 &dists) const
 	{
@@ -69,17 +78,19 @@
 	};
 #endif
 
-	// all intersections (only for CSG)
+	/** get all intersections -- not needed nor used currently */
 	virtual bool intersect_all(const Ray &ray, Float dist, vector<Float> &allts) const = 0;
 
-	// intersection with AABB
+	/** test intersection with bounding box */
 	virtual bool intersect_bbox(const BBox &bbox) const = 0;
 
-	// normal at point P
+	/** get surface normal at point P */
 	virtual const Vector normal(const Vector &P) const = 0;
 
+	/** get bounding box of this shape */
 	virtual BBox get_bbox() const = 0;
 
+	/** write textual representation of the shape to stream */
 	virtual ostream & dump(ostream &st) const = 0;
 };
 
@@ -103,17 +114,20 @@
 		center(acenter), radius(aradius),
 		sqr_radius(aradius*aradius), inv_radius(1.0f/aradius)
 		{ material = amaterial; }
+
 	bool intersect(const Ray &ray, Float &dist) const;
+#ifndef NO_SIMD
+	mfloat4 intersect_packet(const RayPacket &rays, mfloat4 &dists) const;
+#endif
 	bool intersect_all(const Ray &ray, Float dist, vector<Float> &allts) const;
 	bool intersect_bbox(const BBox &bbox) const;
 	const Vector normal(const Vector &P) const { return (P - center) * inv_radius; };
 	BBox get_bbox() const;
+
 	const Vector getCenter() const { return center; };
 	Float getRadius() const { return radius; };
+
 	ostream & dump(ostream &st) const;
-#ifndef NO_SIMD
-	mfloat4 intersect_packet(const RayPacket &rays, mfloat4 &dists) const;
-#endif
 };
 
 /**
@@ -132,16 +146,18 @@
 		material = amaterial;
 	};
 	bool intersect(const Ray &ray, Float &dist) const;
+#ifndef NO_SIMD
+	mfloat4 intersect_packet(const RayPacket &rays, mfloat4 &dists) const;
+#endif
 	bool intersect_all(const Ray &ray, Float dist, vector<Float> &allts) const { return false; };
 	bool intersect_bbox(const BBox &bbox) const;
 	const Vector normal(const Vector &P) const;
 	BBox get_bbox() const { return BBox(L, H); };
+
 	const Vector getL() const { return L; };
 	const Vector getH() const { return H; };
+
 	ostream & dump(ostream &st) const;
-#ifndef NO_SIMD
-	mfloat4 intersect_packet(const RayPacket &rays, mfloat4 &dists) const;
-#endif
 };
 
 /**
@@ -219,17 +235,21 @@
 	Triangle() {};
 	Triangle(Vertex *aA, Vertex *aB, Vertex *aC, Material *amaterial);
 	bool intersect(const Ray &ray, Float &dist) const;
+#if !defined(NO_SIMD) && defined(TRI_BARI_PRE)
+	mfloat4 intersect_packet(const RayPacket &rays, mfloat4 &dists) const;
+#endif
 	bool intersect_all(const Ray &ray, Float dist, vector<Float> &allts) const {return false;};
 	bool intersect_bbox(const BBox &bbox) const;
 	const Vector normal(const Vector &P) const { return (material->smooth ? smooth_normal(P) : N); };
+	BBox get_bbox() const;
+
+	/** get real normal of the triangle */
 	const Vector getNormal() const { return N; };
-	BBox get_bbox() const;
+
 	ostream & dump(ostream &st) const;
-#if !defined(NO_SIMD) && defined(TRI_BARI_PRE)
-	mfloat4 intersect_packet(const RayPacket &rays, mfloat4 &dists) const;
-#endif
 };
 
+/** template for triangle arrays, currently not used */
 template <class T> class Array
 {
 	T *array;