From 8969939c458bda0a5a9c6ad2197e7600e4c71c86 Mon Sep 17 00:00:00 2001
From: Daniel Karbach <daniel.karbach@localhorst.tv>
Date: Fri, 1 Jun 2012 21:05:45 +0000
Subject: [PATCH] some comments

---
 src/app/Timer.h    |  3 +++
 src/shape/AABB.cpp |  6 +++++-
 src/shape/AABB.h   |  2 ++
 src/shape/Shape.h  | 10 ++++++++++
 4 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/app/Timer.h b/src/app/Timer.h
index 997d92c..1b4fdb5 100644
--- a/src/app/Timer.h
+++ b/src/app/Timer.h
@@ -10,6 +10,9 @@
 
 namespace app {
 
+/// Objects of class keep track of the current delta and the time elapsed since
+/// their respective incarnation (which may also be tampered with).
+/// It's also possible to scale the time e.g. for slow-motion or fast-forwarding.
 class Timer {
 
 	public:
diff --git a/src/shape/AABB.cpp b/src/shape/AABB.cpp
index 75007ec..71844e8 100644
--- a/src/shape/AABB.cpp
+++ b/src/shape/AABB.cpp
@@ -17,12 +17,16 @@ void AABB::Translate(const Vector &delta) {
 }
 
 void AABB::Rotate(Scalar delta) {
-
+	// by definition AABBs cannot rotate
 }
 
 
 bool AABB::CheckCollision(const Shape &other, Ray &na) const {
+	// This call reveals the real type of this shape by overloading and the
+	// other one via polymorphism.
 	if (other.CheckCollision(*this, na)) {
+		// Since the other shape's collision check returns its own surface
+		// normal, it has to be inverted here.
 		na.Direction() *= -1;
 		return true;
 	} else {
diff --git a/src/shape/AABB.h b/src/shape/AABB.h
index 956114a..74d0916 100644
--- a/src/shape/AABB.h
+++ b/src/shape/AABB.h
@@ -12,6 +12,8 @@
 
 namespace shape {
 
+/// An axes aligned bounding box.
+/// This shape cannot be rotated.
 class AABB
 : public Shape {
 
diff --git a/src/shape/Shape.h b/src/shape/Shape.h
index 69eedc2..9feb5e1 100644
--- a/src/shape/Shape.h
+++ b/src/shape/Shape.h
@@ -19,6 +19,9 @@ namespace shape {
 class AABB;
 class Circle;
 
+/// Base class for all "shapes" (i.e. collision primitives).
+/// This serves as an interface for game::Entity to double dispatch the
+/// collision detection algorithms.
 class Shape {
 
 	public:
@@ -30,10 +33,17 @@ class Shape {
 		virtual ~Shape(void) { };
 
 	public:
+		/// Move the shape by given delta.
 		virtual void Translate(const Vector &delta) = 0;
+		/// Rotate the shape by given delta (in radians).
 		virtual void Rotate(Scalar delta) = 0;
 
 	public:
+		/// Check if this shape overlaps the given and, if it does, write the
+		/// surface normal into given vector.
+		/// All shapes must override this method to dispatch to the specialized
+		/// version of CheckCollision().
+		/// See AABB::CheckCollision(const Shape &, Ray &) const for details.
 		virtual bool CheckCollision(const Shape &, Ray &) const = 0;
 		virtual bool CheckCollision(const AABB &, Ray &) const = 0;
 		virtual bool CheckCollision(const Circle &, Ray &) const = 0;
-- 
2.39.2