From d5322ad74524eb980764faf8d622b1e6b7afbc04 Mon Sep 17 00:00:00 2001
From: Daniel Chappuis <chappuis.daniel@gmail.com>
Date: Sat, 21 Apr 2018 19:47:35 +0200
Subject: [PATCH] Add comments in the code

---
 src/collision/ContactManifold.h               |  2 +-
 src/collision/HalfEdgeStructure.h             | 25 +++++++++++
 src/collision/PolygonVertexArray.cpp          | 12 +++++
 src/collision/PolygonVertexArray.h            | 28 ++++++++++++
 src/collision/PolyhedronMesh.cpp              |  6 ++-
 src/collision/PolyhedronMesh.h                | 16 +++++++
 src/collision/TriangleMesh.h                  | 12 ++++-
 src/collision/TriangleVertexArray.cpp         | 22 ++++++++-
 src/collision/TriangleVertexArray.h           | 33 ++++++++++++++
 .../narrowphase/CapsuleVsCapsuleAlgorithm.h   |  5 ++-
 .../CapsuleVsConvexPolyhedronAlgorithm.h      | 10 ++++-
 ...vexPolyhedronVsConvexPolyhedronAlgorithm.h |  5 ++-
 src/collision/narrowphase/GJK/GJKAlgorithm.h  |  9 ++--
 src/collision/narrowphase/SAT/SATAlgorithm.h  |  6 +++
 .../narrowphase/SphereVsCapsuleAlgorithm.h    |  3 ++
 .../SphereVsConvexPolyhedronAlgorithm.h       | 11 ++++-
 .../narrowphase/SphereVsSphereAlgorithm.h     |  5 ++-
 src/collision/shapes/SphereShape.h            |  6 +++
 src/constraint/ContactPoint.h                 | 45 +++++++++++++++++++
 src/engine/CollisionWorld.cpp                 | 10 ++++-
 src/engine/CollisionWorld.h                   |  9 ++++
 src/engine/DynamicsWorld.cpp                  |  8 +++-
 src/engine/DynamicsWorld.h                    |  6 +++
 23 files changed, 277 insertions(+), 17 deletions(-)

diff --git a/src/collision/ContactManifold.h b/src/collision/ContactManifold.h
index cfe9af9b..8ca6c3eb 100644
--- a/src/collision/ContactManifold.h
+++ b/src/collision/ContactManifold.h
@@ -83,7 +83,7 @@ struct ContactManifoldListElement {
  * This class represents a set of contact points between two bodies that
  * all have a similar contact normal direction. Usually, there is a single
  * contact manifold when two convex shapes are in contact. However, when
- * a convex shape collides with a concave shape, there can be several
+ * a convex shape collides with a concave shape, there might be several
  * contact manifolds with different normal directions.
  * The contact manifold is implemented in a way to cache the contact
  * points among the frames for better stability (warm starting of the
diff --git a/src/collision/HalfEdgeStructure.h b/src/collision/HalfEdgeStructure.h
index 3f351533..304dfbdf 100644
--- a/src/collision/HalfEdgeStructure.h
+++ b/src/collision/HalfEdgeStructure.h
@@ -126,6 +126,9 @@ class HalfEdgeStructure {
 };
 
 // Add a vertex
+/**
+ * @param vertexPointIndex Index of the vertex in the vertex data array
+ */
 inline uint HalfEdgeStructure::addVertex(uint vertexPointIndex) {
     Vertex vertex(vertexPointIndex);
     mVertices.add(vertex);
@@ -133,6 +136,10 @@ inline uint HalfEdgeStructure::addVertex(uint vertexPointIndex) {
 }
 
 // Add a face
+/**
+ * @param faceVertices List of the vertices in a face (ordered in CCW order as seen from outside
+ *                     the polyhedron
+ */
 inline void HalfEdgeStructure::addFace(List<uint> faceVertices) {
 
     // Create a new face
@@ -141,33 +148,51 @@ inline void HalfEdgeStructure::addFace(List<uint> faceVertices) {
 }
 
 // Return the number of faces
+/**
+ * @return The number of faces in the polyhedron
+ */
 inline uint HalfEdgeStructure::getNbFaces() const {
     return static_cast<uint>(mFaces.size());
 }
 
 // Return the number of edges
+/**
+ * @return The number of edges in the polyhedron
+ */
 inline uint HalfEdgeStructure::getNbHalfEdges() const {
     return static_cast<uint>(mEdges.size());
 }
 
 // Return the number of vertices
+/**
+ * @return The number of vertices in the polyhedron
+ */
 inline uint HalfEdgeStructure::getNbVertices() const {
     return static_cast<uint>(mVertices.size());
 }
 
 // Return a given face
+/**
+ * @return A given face of the polyhedron
+ */
 inline const HalfEdgeStructure::Face& HalfEdgeStructure::getFace(uint index) const {
     assert(index < mFaces.size());
     return mFaces[index];
 }
 
 // Return a given edge
+/**
+ * @return A given edge of the polyhedron
+ */
 inline const HalfEdgeStructure::Edge& HalfEdgeStructure::getHalfEdge(uint index) const {
     assert(index < mEdges.size());
     return mEdges[index];
 }
 
 // Return a given vertex
+/**
+ * @return A given vertex of the polyhedron
+ */
 inline const HalfEdgeStructure::Vertex& HalfEdgeStructure::getVertex(uint index) const {
     assert(index < mVertices.size());
     return mVertices[index];
diff --git a/src/collision/PolygonVertexArray.cpp b/src/collision/PolygonVertexArray.cpp
index 309a0d62..c0da301c 100644
--- a/src/collision/PolygonVertexArray.cpp
+++ b/src/collision/PolygonVertexArray.cpp
@@ -33,6 +33,15 @@ using namespace reactphysics3d;
 /// therefore, you need to make sure that those data are always valid during
 /// the lifetime of the PolygonVertexArray.
 /**
+ * @param nbVertices Number of vertices in the array
+ * @param verticesStart Pointer to the start of the vertices data
+ * @param verticesStride The number of bytes between two consecutive vertices in the array
+ * @param indexesStart Pointer to the start of the face indices data
+ * @param indexesStride The number of bytes between two consecutive face indices in the array
+ * @param nbFaces The number of faces in the array
+ * @param nbFaces Pointer to the start of the faces data
+ * @param vertexDataType Data type of the vertices data
+ * @param indexDataType Data type of the face indices data
  */
 PolygonVertexArray::PolygonVertexArray(uint nbVertices, void* verticesStart, int verticesStride,
                                        void* indexesStart, int indexesStride,
@@ -50,6 +59,9 @@ PolygonVertexArray::PolygonVertexArray(uint nbVertices, void* verticesStart, int
 }
 
 // Return the vertex index of a given vertex in a face
+/**
+ * @return The index of a vertex (in the array of vertices data) of a given vertex in a face
+ */
 uint PolygonVertexArray::getVertexIndexInFace(uint faceIndex, uint noVertexInFace) const {
 
     assert(faceIndex < mNbFaces);
diff --git a/src/collision/PolygonVertexArray.h b/src/collision/PolygonVertexArray.h
index 5ae02e0e..082e9a83 100644
--- a/src/collision/PolygonVertexArray.h
+++ b/src/collision/PolygonVertexArray.h
@@ -137,47 +137,75 @@ class PolygonVertexArray {
 };
 
 // Return the vertex data type
+/**
+ * @return The data type of the vertices in the array
+ */
 inline PolygonVertexArray::VertexDataType PolygonVertexArray::getVertexDataType() const {
     return mVertexDataType;
 }
 
 // Return the index data type
+/**
+ * @return The data type of the indices in the array
+ */
 inline PolygonVertexArray::IndexDataType PolygonVertexArray::getIndexDataType() const {
    return mIndexDataType;
 }
 
 // Return the number of vertices
+/**
+ * @return The number of vertices in the array
+ */
 inline uint PolygonVertexArray::getNbVertices() const {
     return mNbVertices;
 }
 
 // Return the number of faces
+/**
+ * @return The number of faces in the array
+ */
 inline uint PolygonVertexArray::getNbFaces() const {
     return mNbFaces;
 }
 
 // Return the vertices stride (number of bytes)
+/**
+ * @return The number of bytes between two vertices
+ */
 inline int PolygonVertexArray::getVerticesStride() const {
     return mVerticesStride;
 }
 
 // Return the indices stride (number of bytes)
+/**
+ * @return The number of bytes between two consecutive face indices
+ */
 inline int PolygonVertexArray::getIndicesStride() const {
     return mIndicesStride;
 }
 
 // Return a polygon face of the polyhedron
+/**
+ * @param faceIndex Index of a given face
+ * @return A polygon face
+ */
 inline PolygonVertexArray::PolygonFace* PolygonVertexArray::getPolygonFace(uint faceIndex) const {
     assert(faceIndex < mNbFaces);
     return &mPolygonFacesStart[faceIndex];
 }
 
 // Return the pointer to the start of the vertices array
+/**
+ * @return A pointer to the start of the vertex array of the polyhedron
+ */
 inline unsigned char* PolygonVertexArray::getVerticesStart() const {
     return mVerticesStart;
 }
 
 // Return the pointer to the start of the indices array
+/**
+ * @return A pointer to the start of the face indices array of the polyhedron
+ */
 inline unsigned char* PolygonVertexArray::getIndicesStart() const {
     return mIndicesStart;
 }
diff --git a/src/collision/PolyhedronMesh.cpp b/src/collision/PolyhedronMesh.cpp
index 92474c3e..5b910442 100644
--- a/src/collision/PolyhedronMesh.cpp
+++ b/src/collision/PolyhedronMesh.cpp
@@ -32,7 +32,7 @@ using namespace reactphysics3d;
 
 
 // Constructor
-/*
+/**
  * Create a polyhedron mesh given an array of polygons.
  * @param polygonVertexArray Pointer to the array of polygons and their vertices
  */
@@ -94,6 +94,10 @@ void PolyhedronMesh::createHalfEdgeStructure() {
 }
 
 /// Return a vertex
+/**
+ * @param index Index of a given vertex in the mesh
+ * @return The coordinates of a given vertex in the mesh
+ */
 Vector3 PolyhedronMesh::getVertex(uint index) const {
     assert(index < getNbVertices());
 
diff --git a/src/collision/PolyhedronMesh.h b/src/collision/PolyhedronMesh.h
index 07da6f46..c525afd2 100644
--- a/src/collision/PolyhedronMesh.h
+++ b/src/collision/PolyhedronMesh.h
@@ -101,27 +101,43 @@ class PolyhedronMesh {
 };
 
 // Return the number of vertices
+/**
+ * @return The number of vertices in the mesh
+ */
 inline uint PolyhedronMesh::getNbVertices() const {
     return mHalfEdgeStructure.getNbVertices();
 }
 
 // Return the number of faces
+/**
+ * @return The number of faces in the mesh
+ */
 inline uint PolyhedronMesh::getNbFaces() const {
    return mHalfEdgeStructure.getNbFaces();
 }
 
 // Return a face normal
+/**
+ * @param faceIndex The index of a given face of the mesh
+ * @return The normal vector of a given face of the mesh
+ */
 inline Vector3 PolyhedronMesh::getFaceNormal(uint faceIndex) const {
     assert(faceIndex < mHalfEdgeStructure.getNbFaces());
     return mFacesNormals[faceIndex];
 }
 
 // Return the half-edge structure of the mesh
+/**
+ * @return The Half-Edge structure of the mesh
+ */
 inline const HalfEdgeStructure& PolyhedronMesh::getHalfEdgeStructure() const {
     return mHalfEdgeStructure;
 }
 
 // Return the centroid of the polyhedron
+/**
+ * @return The centroid of the mesh
+ */
 inline Vector3 PolyhedronMesh::getCentroid() const {
     return mCentroid;
 }
diff --git a/src/collision/TriangleMesh.h b/src/collision/TriangleMesh.h
index 673a7b52..50f4aeff 100644
--- a/src/collision/TriangleMesh.h
+++ b/src/collision/TriangleMesh.h
@@ -70,17 +70,27 @@ class TriangleMesh {
 };
 
 // Add a subpart of the mesh
+/**
+ * @param triangleVertexArray Pointer to the TriangleVertexArray to add into the mesh
+ */
 inline void TriangleMesh::addSubpart(TriangleVertexArray* triangleVertexArray) {
     mTriangleArrays.add(triangleVertexArray );
 }
 
 // Return a pointer to a given subpart (triangle vertex array) of the mesh
+/**
+ * @param indexSubpart The index of the sub-part of the mesh
+ * @return A pointer to the triangle vertex array of a given sub-part of the mesh
+ */
 inline TriangleVertexArray* TriangleMesh::getSubpart(uint indexSubpart) const {
    assert(indexSubpart < mTriangleArrays.size());
    return mTriangleArrays[indexSubpart];
 }
 
-// Return the number of subparts of the mesh
+// Return the number of sub-parts of the mesh
+/**
+ * @return The number of sub-parts of the mesh
+ */
 inline uint TriangleMesh::getNbSubparts() const {
     return mTriangleArrays.size();
 }
diff --git a/src/collision/TriangleVertexArray.cpp b/src/collision/TriangleVertexArray.cpp
index a54ad425..6298297f 100644
--- a/src/collision/TriangleVertexArray.cpp
+++ b/src/collision/TriangleVertexArray.cpp
@@ -190,6 +190,10 @@ void TriangleVertexArray::computeVerticesNormals() {
 }
 
 // Return the indices of the three vertices of a given triangle in the array
+/**
+ * @param triangleIndex Index of a given triangle in the array
+ * @param[out] outVerticesIndices Pointer to the three output vertex indices
+ */
 void TriangleVertexArray::getTriangleVerticesIndices(uint triangleIndex, uint* outVerticesIndices) const {
 
     assert(triangleIndex >= 0 && triangleIndex < mNbTriangles);
@@ -213,7 +217,11 @@ void TriangleVertexArray::getTriangleVerticesIndices(uint triangleIndex, uint* o
     }
 }
 
-// Return the vertices coordinates of a triangle
+// Return the three vertices coordinates of a triangle
+/**
+ * @param triangleIndex Index of a given triangle in the array
+ * @param[out] outTriangleVertices Pointer to the three output vertex coordinates
+ */
 void TriangleVertexArray::getTriangleVertices(uint triangleIndex, Vector3* outTriangleVertices) const {
 
     assert(triangleIndex >= 0 && triangleIndex < mNbTriangles);
@@ -248,6 +256,10 @@ void TriangleVertexArray::getTriangleVertices(uint triangleIndex, Vector3* outTr
 }
 
 // Return the three vertices normals of a triangle
+/**
+ * @param triangleIndex Index of a given triangle in the array
+ * @param[out] outTriangleVerticesNormals Pointer to the three output vertex normals
+ */
 void TriangleVertexArray::getTriangleVerticesNormals(uint triangleIndex, Vector3* outTriangleVerticesNormals) const {
 
     assert(triangleIndex >= 0 && triangleIndex < mNbTriangles);
@@ -282,6 +294,10 @@ void TriangleVertexArray::getTriangleVerticesNormals(uint triangleIndex, Vector3
 }
 
 // Return a vertex of the array
+/**
+ * @param vertexIndex Index of a given vertex of the array
+ * @param[out] outVertex Pointer to the output vertex coordinates
+ */
 void TriangleVertexArray::getVertex(uint vertexIndex, Vector3* outVertex) {
 
     assert(vertexIndex < mNbVertices);
@@ -308,6 +324,10 @@ void TriangleVertexArray::getVertex(uint vertexIndex, Vector3* outVertex) {
 }
 
 // Return a vertex normal of the array
+/**
+ * @param vertexIndex Index of a given vertex of the array
+ * @param[out] outNormal Pointer to the output vertex normal
+ */
 void TriangleVertexArray::getNormal(uint vertexIndex, Vector3* outNormal) {
 
     assert(vertexIndex < mNbVertices);
diff --git a/src/collision/TriangleVertexArray.h b/src/collision/TriangleVertexArray.h
index 7bc37593..17d16d2b 100644
--- a/src/collision/TriangleVertexArray.h
+++ b/src/collision/TriangleVertexArray.h
@@ -179,56 +179,89 @@ class TriangleVertexArray {
 };
 
 // Return the vertex data type
+/**
+ * @return The data type of the vertices in the array
+ */
 inline TriangleVertexArray::VertexDataType TriangleVertexArray::getVertexDataType() const {
     return mVertexDataType;
 }
 
 // Return the vertex normal data type
+/**
+ * @return The data type of the normals in the array
+ */
 inline TriangleVertexArray::NormalDataType TriangleVertexArray::getVertexNormalDataType() const {
     return mVertexNormaldDataType;
 }
 
 // Return the index data type
+/**
+ * @return The data type of the face indices in the array
+ */
 inline TriangleVertexArray::IndexDataType TriangleVertexArray::getIndexDataType() const {
    return mIndexDataType;
 }
 
 // Return the number of vertices
+/**
+ * @return The number of vertices in the array
+ */
 inline uint TriangleVertexArray::getNbVertices() const {
     return mNbVertices;
 }
 
 // Return the number of triangles
+/**
+ * @return The number of triangles in the array
+ */
 inline uint TriangleVertexArray::getNbTriangles() const {
     return mNbTriangles;
 }
 
 // Return the vertices stride (number of bytes)
+/**
+ * @return The number of bytes separating two consecutive vertices in the array
+ */
 inline uint TriangleVertexArray::getVerticesStride() const {
     return mVerticesStride;
 }
 
 // Return the vertex normals stride (number of bytes)
+/**
+ * @return The number of bytes separating two consecutive normals in the array
+ */
 inline uint TriangleVertexArray::getVerticesNormalsStride() const {
     return mVerticesNormalsStride;
 }
 
 // Return the indices stride (number of bytes)
+/**
+ * @return The number of bytes separating two consecutive face indices in the array
+ */
 inline uint TriangleVertexArray::getIndicesStride() const {
     return mIndicesStride;
 }
 
 // Return the pointer to the start of the vertices array
+/**
+ * @return A pointer to the start of the vertices data in the array
+ */
 inline const void* TriangleVertexArray::getVerticesStart() const {
     return mVerticesStart;
 }
 
 // Return the pointer to the start of the vertex normals array
+/**
+ * @return A pointer to the start of the normals data in the array
+ */
 inline const void* TriangleVertexArray::getVerticesNormalsStart() const {
     return mVerticesNormalsStart;
 }
 
 // Return the pointer to the start of the indices array
+/**
+ * @return A pointer to the start of the face indices data in the array
+ */
 inline const void* TriangleVertexArray::getIndicesStart() const {
     return mIndicesStart;
 }
diff --git a/src/collision/narrowphase/CapsuleVsCapsuleAlgorithm.h b/src/collision/narrowphase/CapsuleVsCapsuleAlgorithm.h
index 181ddf25..3c869cb9 100644
--- a/src/collision/narrowphase/CapsuleVsCapsuleAlgorithm.h
+++ b/src/collision/narrowphase/CapsuleVsCapsuleAlgorithm.h
@@ -39,7 +39,10 @@ class ContactPoint;
 // Class CapsuleVsCapsuleAlgorithm
 /**
  * This class is used to compute the narrow-phase collision detection
- * between two capsules collision shapes.
+ * between two capsules collision shapes. We do not use the GJK or SAT
+ * algorithm here. We directly compute the contact points and contact normal.
+ * This is based on the "Robust Contact Creation for Physics Simulation"
+ * presentation by Dirk Gregorius.
  */
 class CapsuleVsCapsuleAlgorithm : public NarrowPhaseAlgorithm {
 
diff --git a/src/collision/narrowphase/CapsuleVsConvexPolyhedronAlgorithm.h b/src/collision/narrowphase/CapsuleVsConvexPolyhedronAlgorithm.h
index ca0aaf26..6de04307 100644
--- a/src/collision/narrowphase/CapsuleVsConvexPolyhedronAlgorithm.h
+++ b/src/collision/narrowphase/CapsuleVsConvexPolyhedronAlgorithm.h
@@ -39,7 +39,15 @@ class Body;
 // Class CapsuleVsConvexPolyhedronAlgorithm
 /**
  * This class is used to compute the narrow-phase collision detection
- * between a capsule and a convex polyhedron.
+ * between a capsule and a convex polyhedron. The capsule is basically
+ * a line segment with a margin around it. First we run the GJK algorithm.
+ * If GJK reports separation, we are done. If the objects overlap inside the
+ * capsule margin (radius), it will also report contact points and normal.
+ * However, if GJK report penetration of the capsule inner segment within
+ * the polyhedron, we run the SAT algorithm to get the contact points and
+ * normal.
+ * This is based on the "Robust Contact Creation for Physics Simulation"
+ * presentation by Dirk Gregorius.
  */
 class CapsuleVsConvexPolyhedronAlgorithm : public NarrowPhaseAlgorithm {
 
diff --git a/src/collision/narrowphase/ConvexPolyhedronVsConvexPolyhedronAlgorithm.h b/src/collision/narrowphase/ConvexPolyhedronVsConvexPolyhedronAlgorithm.h
index a60bfa9a..1db470b1 100644
--- a/src/collision/narrowphase/ConvexPolyhedronVsConvexPolyhedronAlgorithm.h
+++ b/src/collision/narrowphase/ConvexPolyhedronVsConvexPolyhedronAlgorithm.h
@@ -39,7 +39,10 @@ class ContactPoint;
 // Class ConvexPolyhedronVsConvexPolyhedronAlgorithm
 /**
  * This class is used to compute the narrow-phase collision detection
- * between two convex polyhedra.
+ * between two convex polyhedra. Here we do not use the GJK algorithm but
+ * we run the SAT algorithm to get the contact points and normal.
+ * This is based on the "Robust Contact Creation for Physics Simulation"
+ * presentation by Dirk Gregorius.
  */
 class ConvexPolyhedronVsConvexPolyhedronAlgorithm : public NarrowPhaseAlgorithm {
 
diff --git a/src/collision/narrowphase/GJK/GJKAlgorithm.h b/src/collision/narrowphase/GJK/GJKAlgorithm.h
index 5743e036..4a5f23a0 100644
--- a/src/collision/narrowphase/GJK/GJKAlgorithm.h
+++ b/src/collision/narrowphase/GJK/GJKAlgorithm.h
@@ -47,18 +47,15 @@ constexpr int MAX_ITERATIONS_GJK_RAYCAST = 32;
 // Class GJKAlgorithm
 /**
  * This class implements a narrow-phase collision detection algorithm. This
- * algorithm uses the ISA-GJK algorithm and the EPA algorithm. This
+ * algorithm uses the ISA-GJK algorithm. This
  * implementation is based on the implementation discussed in the book
  * "Collision Detection in Interactive 3D Environments" by Gino van den Bergen.
  * This method implements the Hybrid Technique for calculating the
  * penetration depth. The two objects are enlarged with a small margin. If
  * the object intersects in their margins, the penetration depth is quickly
  * computed using the GJK algorithm on the original objects (without margin).
- * If the original objects (without margin) intersect, we run again the GJK
- * algorithm on the enlarged objects (with margin) to compute simplex
- * polytope that contains the origin and give it to the EPA (Expanding
- * Polytope Algorithm) to compute the correct penetration depth between the
- * enlarged objects.
+ * If the original objects (without margin) intersect, we exit GJK and run
+ * the SAT algorithm to get contacts and collision data.
  */
 class GJKAlgorithm {
 
diff --git a/src/collision/narrowphase/SAT/SATAlgorithm.h b/src/collision/narrowphase/SAT/SATAlgorithm.h
index 9c8e2d21..2b44b13c 100644
--- a/src/collision/narrowphase/SAT/SATAlgorithm.h
+++ b/src/collision/narrowphase/SAT/SATAlgorithm.h
@@ -43,6 +43,12 @@ class MemoryAllocator;
 class Profiler;
 
 // Class SATAlgorithm
+/**
+ * This class implements the Separating Axis Theorem algorithm (SAT).
+ * This algorithm is used to find the axis of minimum penetration between two convex polyhedra.
+ * If none is found, the objects are separated. Otherwise, the two objects are
+ * in contact and we use clipping to get the contact points.
+ */
 class SATAlgorithm {
 
     private :
diff --git a/src/collision/narrowphase/SphereVsCapsuleAlgorithm.h b/src/collision/narrowphase/SphereVsCapsuleAlgorithm.h
index 9d81cc2e..84b5a130 100644
--- a/src/collision/narrowphase/SphereVsCapsuleAlgorithm.h
+++ b/src/collision/narrowphase/SphereVsCapsuleAlgorithm.h
@@ -41,6 +41,9 @@ class ContactPoint;
 /**
  * This class is used to compute the narrow-phase collision detection
  * between a sphere collision shape and a capsule collision shape.
+ * For this case, we do not use GJK or SAT algorithm. We directly compute the
+ * contact points and contact normal. This is based on the "Robust Contact
+ * Creation for Physics Simulation" presentation by Dirk Gregorius.
  */
 class SphereVsCapsuleAlgorithm : public NarrowPhaseAlgorithm {
 
diff --git a/src/collision/narrowphase/SphereVsConvexPolyhedronAlgorithm.h b/src/collision/narrowphase/SphereVsConvexPolyhedronAlgorithm.h
index f105b967..ed14dcb0 100644
--- a/src/collision/narrowphase/SphereVsConvexPolyhedronAlgorithm.h
+++ b/src/collision/narrowphase/SphereVsConvexPolyhedronAlgorithm.h
@@ -39,7 +39,16 @@ class Body;
 // Class SphereVsConvexPolyhedronAlgorithm
 /**
  * This class is used to compute the narrow-phase collision detection
- * between a sphere and a convex polyhedron.
+ * between a sphere and a convex polyhedron. The sphere is basically a
+ * point with a margin around it. The idea of this method is to use
+ * the GJK algorithm first. If GJK reports that the two objects are
+ * separated, we are done. If GJK reports that the objects are overlapping
+ * in the sphere margin, GJK will also report a contact point and a contact
+ * normal. However, if GJK reports that the object are in deep penetration
+ * (the center of the sphere is inside the polyhedron) we run the SAT
+ * algorithm to get the contact point and contact normal.
+ * This is based on the "Robust Contact Creation for Physics Simulation"
+ * presentation by Dirk Gregorius.
  */
 class SphereVsConvexPolyhedronAlgorithm : public NarrowPhaseAlgorithm {
 
diff --git a/src/collision/narrowphase/SphereVsSphereAlgorithm.h b/src/collision/narrowphase/SphereVsSphereAlgorithm.h
index 2cf04951..9679571d 100644
--- a/src/collision/narrowphase/SphereVsSphereAlgorithm.h
+++ b/src/collision/narrowphase/SphereVsSphereAlgorithm.h
@@ -39,7 +39,10 @@ class Body;
 // Class SphereVsSphereAlgorithm
 /**
  * This class is used to compute the narrow-phase collision detection
- * between two sphere collision shapes.
+ * between two sphere collision shapes. This algorithm finds the contact
+ * point and contact normal between two spheres if they are colliding.
+ * This case is simple, we do not need to use GJK or SAT algorithm. We
+ * directly compute the contact points if any.
  */
 class SphereVsSphereAlgorithm : public NarrowPhaseAlgorithm {
 
diff --git a/src/collision/shapes/SphereShape.h b/src/collision/shapes/SphereShape.h
index 7b6f5b32..9793f9d9 100644
--- a/src/collision/shapes/SphereShape.h
+++ b/src/collision/shapes/SphereShape.h
@@ -106,11 +106,17 @@ inline decimal SphereShape::getRadius() const {
 }
 
 // Return true if the collision shape is a polyhedron
+/**
+ * @return False because the sphere shape is not a polyhedron
+ */
 inline bool SphereShape::isPolyhedron() const {
         return false;
 }
 
 // Return the number of bytes used by the collision shape
+/**
+ * @return The size (in bytes) of the sphere shape
+ */
 inline size_t SphereShape::getSizeInBytes() const {
     return sizeof(SphereShape);
 }
diff --git a/src/constraint/ContactPoint.h b/src/constraint/ContactPoint.h
index afe78cb7..99cf66d1 100644
--- a/src/constraint/ContactPoint.h
+++ b/src/constraint/ContactPoint.h
@@ -157,21 +157,33 @@ class ContactPoint {
 };
 
 // Return the normal vector of the contact
+/**
+ * @return The contact normal
+ */
 inline Vector3 ContactPoint::getNormal() const {
     return mNormal;
 }
 
 // Return the contact point on the first proxy shape in the local-space of the proxy shape
+/**
+ * @return The contact point on the first proxy shape in the local-space of the proxy shape
+ */
 inline const Vector3& ContactPoint::getLocalPointOnShape1() const {
     return mLocalPointOnShape1;
 }
 
 // Return the contact point on the second proxy shape in the local-space of the proxy shape
+/**
+ * @return The contact point on the second proxy shape in the local-space of the proxy shape
+ */
 inline const Vector3& ContactPoint::getLocalPointOnShape2() const {
     return mLocalPointOnShape2;
 }
 
 // Return the cached penetration impulse
+/**
+ * @return The penetration impulse
+ */
 inline decimal ContactPoint::getPenetrationImpulse() const {
     return mPenetrationImpulse;
 }
@@ -183,56 +195,89 @@ inline bool ContactPoint::isSimilarWithContactPoint(const ContactPointInfo* loca
 }
 
 // Set the cached penetration impulse
+/**
+ * @param impulse Penetration impulse
+ */
 inline void ContactPoint::setPenetrationImpulse(decimal impulse) {
     mPenetrationImpulse = impulse;
 }
 
 // Return true if the contact is a resting contact
+/**
+ * @return True if it is a resting contact
+ */
 inline bool ContactPoint::getIsRestingContact() const {
     return mIsRestingContact;
 }
 
 // Set the mIsRestingContact variable
+/**
+ * @param isRestingContact True if it is a resting contact
+ */
 inline void ContactPoint::setIsRestingContact(bool isRestingContact) {
     mIsRestingContact = isRestingContact;
 }
 
 // Return true if the contact point is obsolete
+/**
+ * @return True if the contact is obsolete
+ */
 inline bool ContactPoint::getIsObsolete() const {
     return mIsObsolete;
 }
 
 // Set to true to make the contact point obsolete
+/**
+ * @param isObsolete True if the contact is obsolete
+ */
 inline void ContactPoint::setIsObsolete(bool isObsolete) {
     mIsObsolete = isObsolete;
 }
 
 // Return the next contact point in the linked list
+/**
+ * @return A pointer to the next contact point in the linked-list of points
+ */
 inline ContactPoint* ContactPoint::getNext() const {
    return mNext;
 }
 
 // Set the next contact point in the linked list
+/**
+ * @param next Pointer to the next contact point in the linked-list of points
+ */
 inline void ContactPoint::setNext(ContactPoint* next) {
     mNext = next;
 }
 
 // Return the previous contact point in the linked list
+/**
+ * @return A pointer to the previous contact point in the linked-list of points
+ */
 inline ContactPoint* ContactPoint::getPrevious() const {
    return mPrevious;
 }
 
 // Set the previous contact point in the linked list
+/**
+ * @param previous Pointer to the previous contact point in the linked-list of points
+ */
 inline void ContactPoint::setPrevious(ContactPoint* previous) {
     mPrevious = previous;
 }
 
 // Return the penetration depth of the contact
+/**
+ * @return the penetration depth (in meters)
+ */
 inline decimal ContactPoint::getPenetrationDepth() const {
     return mPenetrationDepth;
 }
 
 // Return the number of bytes used by the contact point
+/**
+ * @return The size of the contact point in memory (in bytes)
+ */
 inline size_t ContactPoint::getSizeInBytes() const {
     return sizeof(ContactPoint);
 }
diff --git a/src/engine/CollisionWorld.cpp b/src/engine/CollisionWorld.cpp
index 988d2ad0..d92f168e 100644
--- a/src/engine/CollisionWorld.cpp
+++ b/src/engine/CollisionWorld.cpp
@@ -255,12 +255,20 @@ inline void CollisionWorld::testAABBOverlap(const AABB& aabb, OverlapCallback* o
 }
 
 // Return true if two bodies overlap
+/**
+ * @param body1 Pointer to the first body
+ * @param body2 Pointer to a second body
+ * @return True if the two bodies overlap
+ */
 bool CollisionWorld::testOverlap(CollisionBody* body1, CollisionBody* body2) {
     return mCollisionDetection.testOverlap(body1, body2);
 }
 
-
 // Return the current world-space AABB of given proxy shape
+/**
+ * @param proxyShape Pointer to a proxy shape
+ * @return The AAABB of the proxy shape in world-space
+ */
 AABB CollisionWorld::getWorldAABB(const ProxyShape* proxyShape) const {
 
     if (proxyShape->getBroadPhaseId() == -1) {
diff --git a/src/engine/CollisionWorld.h b/src/engine/CollisionWorld.h
index acc9ad40..935b08dd 100644
--- a/src/engine/CollisionWorld.h
+++ b/src/engine/CollisionWorld.h
@@ -256,6 +256,9 @@ inline void CollisionWorld::testOverlap(CollisionBody* body, OverlapCallback* ov
 }
 
 // Return the name of the world
+/**
+ * @return Name of the world
+ */
 inline const std::string& CollisionWorld::getName() const {
     return mName;
 }
@@ -263,6 +266,9 @@ inline const std::string& CollisionWorld::getName() const {
 #ifdef IS_PROFILING_ACTIVE
 
 // Return a pointer to the profiler
+/**
+ * @return A pointer to the profiler
+ */
 inline Profiler* CollisionWorld::getProfiler() {
     return mProfiler;
 }
@@ -272,6 +278,9 @@ inline Profiler* CollisionWorld::getProfiler() {
 #ifdef IS_LOGGING_ACTIVE
 
 // Return a pointer to the logger
+/**
+ * @return A pointer to the logger
+ */
 inline Logger* CollisionWorld::getLogger() {
     return mLogger;
 }
diff --git a/src/engine/DynamicsWorld.cpp b/src/engine/DynamicsWorld.cpp
index f1698563..31e8022d 100644
--- a/src/engine/DynamicsWorld.cpp
+++ b/src/engine/DynamicsWorld.cpp
@@ -41,6 +41,9 @@ using namespace std;
 // Constructor
 /**
  * @param gravity Gravity vector in the world (in meters per second squared)
+ * @param worldSettings The settings of the world
+ * @param logger Pointer to the logger
+ * @param profiler Pointer to the profiler
  */
 DynamicsWorld::DynamicsWorld(const Vector3& gravity, const WorldSettings& worldSettings,
                              Logger* logger, Profiler* profiler)
@@ -882,7 +885,10 @@ void DynamicsWorld::enableSleeping(bool isSleepingEnabled) {
              "Dynamics World: isSleepingEnabled=" + (isSleepingEnabled ? std::string("true") : std::string("false")) );
 }
 
-/// Return the list of all contacts of the world
+// Return the list of all contacts of the world
+/**
+ * @return A pointer to the first contact manifold in the linked-list of manifolds
+ */
 List<const ContactManifold*> DynamicsWorld::getContactsList() {
 
     List<const ContactManifold*> contactManifolds(mMemoryManager.getPoolAllocator());
diff --git a/src/engine/DynamicsWorld.h b/src/engine/DynamicsWorld.h
index 570fac45..a5361dd6 100644
--- a/src/engine/DynamicsWorld.h
+++ b/src/engine/DynamicsWorld.h
@@ -275,6 +275,9 @@ inline void DynamicsWorld::resetBodiesForceAndTorque() {
 }
 
 // Get the number of iterations for the velocity constraint solver
+/**
+ * @return The number of iterations of the velocity constraint solver
+ */
 inline uint DynamicsWorld::getNbIterationsVelocitySolver() const {
     return mNbVelocitySolverIterations;
 }
@@ -291,6 +294,9 @@ inline void DynamicsWorld::setNbIterationsVelocitySolver(uint nbIterations) {
 }
 
 // Get the number of iterations for the position constraint solver
+/**
+ * @return The number of iterations of the position constraint solver
+ */
 inline uint DynamicsWorld::getNbIterationsPositionSolver() const {
     return mNbPositionSolverIterations;
 }