Document the merge code

tools/qfbsp/include/merge.h

@@ -23,9 +23,40 @@
 #ifndef qfbsp_merge_h
 #define qfbsp_merge_h
 
-void MergePlaneFaces (surface_t *plane);
+/**	Add a face to the list of faces, doing any possible merging.
+
+	\param face		The face to add to the list.
+	\param list		The list to which the face will be added.
+	\return			The list with the plane added or merged to other faces in
+					the list.
+*/
 face_t *MergeFaceToList (face_t *face, face_t *list);
+
+/**	Remove merged out faces from the list.
+
+	Removes faces that MergeFaceToList() wanted to remove but couldn't due to
+	its implementation.
+
+	\param merged	The list of merged faces.
+	\return			The cleaned list.
+
+	\note			The list is reversed in the process.
+
+	\todo Reimplement MergeFaceToList() such that this function is no longer
+	needed.
+*/
 face_t *FreeMergeListScraps (face_t *merged);
+
+/**	Process the faces on a surface, searching for mergable faces.
+
+	\param plane	The surface of which the faces will be processed.
+*/
+void MergePlaneFaces (surface_t *plane);
+
+/**	Process the faces on a list of suraces.
+
+	\param surfhead	The list of surfaces.
+*/
 void MergeAll (surface_t *surfhead);
 
 #endif//qfbsp_merge_h

tools/qfbsp/source/merge.c

@@ -37,17 +37,21 @@ static __attribute__ ((used)) const char rcsid[] =
 #define CONTINUOUS_EPSILON	0.001
 
 
-/*
-	TryMerge
+/**	Try to merge two polygons.
 
 	If two polygons share a common edge and the edges that meet at the common
-	points are both inside the other polygons, merge them
+	points are both inside the other polygons, merge them. The two polygons
+	must be on the same plane, the same side of the plane, have the same
+	texture and have the same contents on each side.
 
-	Returns NULL if the faces couldn't be merged, or the new face.
-	The originals will NOT be freed.
+	\param f1		The first face.
+	\param f2		The second face.
+	\return			The new face or NULL if the faces could not be merged.
+
+	\note The originals will NOT be freed.
 */
-static face_t     *
-TryMerge (face_t *f1, face_t *f2)
+static face_t *
+TryMerge (const face_t *f1, const face_t *f2)
 {
 	face_t     *newf;
 	int         i, j, k, l;
@@ -69,10 +73,10 @@ TryMerge (face_t *f1, face_t *f2)
 	if (f1->contents[1] != f2->contents[1])
 		return NULL;
 
-	// find a common edge
-	p1 = p2 = NULL;						// stop compiler warning
+	p1 = p2 = NULL;
 	j = 0;
 
+	// find a common edge
 	for (i = 0; i < f1p->numpoints; i++) {
 		p1 = f1p->points[i];
 		p2 = f1p->points[(i + 1) % f1p->numpoints];
@@ -149,7 +153,7 @@ found_edge:
 }
 
 qboolean    mergedebug;
-face_t     *
+face_t *
 MergeFaceToList (face_t *face, face_t *list)
 {
 	face_t     *newf, *f;
@@ -176,7 +180,7 @@ MergeFaceToList (face_t *face, face_t *list)
 	return face;
 }
 
-face_t     *
+face_t *
 FreeMergeListScraps (face_t *merged)
 {
 	face_t     *head, *next;