From a8bd522ca1abadb517075a26fa724e9929f509c0 Mon Sep 17 00:00:00 2001
From: Bill Currie <bill@taniwha.org>
Date: Mon, 30 Aug 2010 23:19:42 +0900
Subject: [PATCH] Documentation for tjunc.

---
 tools/qfbsp/include/tjunc.h |  4 +++
 tools/qfbsp/source/tjunc.c  | 72 ++++++++++++++++++++++++++++++++++---
 2 files changed, 71 insertions(+), 5 deletions(-)

diff --git a/tools/qfbsp/include/tjunc.h b/tools/qfbsp/include/tjunc.h
index e78a076c4..ac0ee3f61 100644
--- a/tools/qfbsp/include/tjunc.h
+++ b/tools/qfbsp/include/tjunc.h
@@ -25,6 +25,10 @@
 
 struct node_s;
 
+/**	Add the edges from the faces in the bsp tree.
+
+	\param headnode	The current node in the bsp tree.
+*/
 void tjunc (struct node_s *headnode);
 
 #endif//qfbsp_tjunc_h
diff --git a/tools/qfbsp/source/tjunc.c b/tools/qfbsp/source/tjunc.c
index 9758e2f2d..3c052cbca 100644
--- a/tools/qfbsp/source/tjunc.c
+++ b/tools/qfbsp/source/tjunc.c
@@ -67,6 +67,11 @@ wedge_t    *wedge_hash[NUM_HASH];
 
 static vec3_t hash_min, hash_scale;
 
+/**	Initialize the edge hash table.
+
+	\param mins		The minimum of the bounding box in which the edges reside.
+	\param maxs		The maximum of the bounding box in which the edges reside.
+*/
 static void
 InitHash (vec3_t mins, vec3_t maxs)
 {
@@ -91,6 +96,11 @@ InitHash (vec3_t mins, vec3_t maxs)
 	hash_scale[2] = newsize[1];
 }
 
+/**	Calulate the hash value of a vector.
+
+	\param vec		The vector for which to calculate the hash value.
+	\return			The hash value of the vector.
+*/
 static unsigned
 HashVec (vec3_t vec)
 {
@@ -103,6 +113,14 @@ HashVec (vec3_t vec)
 	return h;
 }
 
+/**	Make the vector canonical.
+
+	A canonical vector is a unit vector with the first non-zero axis
+	positive.
+
+	\param vec		The vector to make canonical.
+	\return			false is the vector is (0, 0, 0), otherwise true.
+*/
 static qboolean
 CanonicalVector (vec3_t vec)
 {
@@ -140,6 +158,21 @@ CanonicalVector (vec3_t vec)
 	return false;
 }
 
+/**	Find a wedge for the two points.
+
+	A wedge is an infinitely long line passing through the two points with
+	an "origin" at t=0.
+
+	\param p1		The first point.
+	\param p2		The second point.
+	\param t1		The "time" of one of the points.
+	\param t2		The "time" of the other point.
+	\return			Pointer to the wedge, or NULL for a degenerate edge
+					(zero length).
+
+	\note t2 will always be greater than t1, so there's no guarantee which
+	point is represented by t1 and t2.
+*/
 static wedge_t *
 FindEdge (vec3_t p1, vec3_t p2, vec_t *t1, vec_t *t2)
 {
@@ -161,6 +194,7 @@ FindEdge (vec3_t p1, vec3_t p2, vec_t *t1, vec_t *t2)
 	VectorMultSub (p1, *t1, dir, origin);
 
 	if (*t1 > *t2) {
+		// swap t1 and t2
 		temp = *t1;
 		*t1 = *t2;
 		*t2 = temp;
@@ -176,6 +210,7 @@ FindEdge (vec3_t p1, vec3_t p2, vec_t *t1, vec_t *t2)
 		return w;
 	}
 
+	// create a new wedge
 	if (numwedges == MAXWEDGES)
 		Sys_Error ("FindEdge: numwedges == MAXWEDGES");
 	w = &wedges[numwedges];
@@ -193,6 +228,16 @@ FindEdge (vec3_t p1, vec3_t p2, vec_t *t1, vec_t *t2)
 
 #define	T_EPSILON	0.01
 
+/**	Add a wvert to the wedge.
+
+	A wvert is a vertex on the wedge and is specified by the time along the
+	wedge from the wedge's origin.
+
+	If a wvert with the same time already exists, a new one will not be added.
+
+	\param w		The wedge to which the wvert will be added.
+	\param t		The "time" of the wvert.
+*/
 static void
 AddVert (wedge_t *w, vec_t t)
 {
@@ -221,6 +266,11 @@ AddVert (wedge_t *w, vec_t t)
 	v->prev = newv;
 }
 
+/**	Add a faces edge to the wedge system.
+
+	\param p1		The first point of the face's edge.
+	\param p2		The second point of the face's edge.
+*/
 static void
 AddEdge (vec3_t p1, vec3_t p2)
 {
@@ -233,6 +283,10 @@ AddEdge (vec3_t p1, vec3_t p2)
 	}
 }
 
+/**	Add the edges from the face.
+
+	\param f		The face from which to add the faces.
+*/
 static void
 AddFaceEdges (face_t *f)
 {
@@ -246,6 +300,13 @@ AddFaceEdges (face_t *f)
 
 face_t     *newlist;
 
+/**	Check and fix the edges of the face.
+
+	If any vertices from other faces lie on an edge of the face between the
+	edge's end points, add matching vertices along that edge.
+
+	\param f		The face of which the edges will be checked.
+*/
 static void
 FixFaceEdges (face_t *f)
 {
@@ -284,8 +345,6 @@ FixFaceEdges (face_t *f)
 	newlist = f;
 }
 
-//============================================================================
-
 static void
 tjunc_find_r (node_t *node)
 {
@@ -302,6 +361,10 @@ tjunc_find_r (node_t *node)
 	tjunc_find_r (node->children[1]);
 }
 
+/**	Check and fix the edges from the faces in the bsp tree.
+
+	\param node		The current node in the bsp tree.
+*/
 static void
 tjunc_fix_r (node_t *node)
 {
@@ -336,9 +399,7 @@ tjunc (node_t *headnode)
 	if (options.notjunc)
 		return;
 
-	// identify all points on common edges
-
-	// origin points won't allways be inside the map, so extend the hash area 
+	// origin points won't allways be inside the map, so extend the hash area
 	for (i = 0; i < 3; i++) {
 		if (fabs (brushset->maxs[i]) > fabs (brushset->mins[i]))
 			maxs[i] = fabs (brushset->maxs[i]);
@@ -351,6 +412,7 @@ tjunc (node_t *headnode)
 
 	numwedges = numwverts = 0;
 
+	// identify all points on common edges
 	tjunc_find_r (headnode);
 
 	qprintf ("%i world edges  %i edge points\n", numwedges, numwverts);