From 2e6eb419ca88ed1bc851cc5cedff913949998fb6 Mon Sep 17 00:00:00 2001
From: Bill Currie <bill@taniwha.org>
Date: Sat, 28 Aug 2010 22:04:58 +0900
Subject: [PATCH] Some documentation for the map parser.

---
 tools/qfbsp/include/map.h | 56 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 52 insertions(+), 4 deletions(-)

diff --git a/tools/qfbsp/include/map.h b/tools/qfbsp/include/map.h
index a4563a91e..32ed2441f 100644
--- a/tools/qfbsp/include/map.h
+++ b/tools/qfbsp/include/map.h
@@ -35,7 +35,7 @@ typedef struct mface_s {
 typedef struct mbrush_s {
 	struct mbrush_s *next;
 	mface_t    *faces;
-	qboolean    detail;	// true if brush is detail brush
+	qboolean    detail;			///< true if brush is detail brush
 } mbrush_t;
 
 typedef struct epair_s {
@@ -44,10 +44,12 @@ typedef struct epair_s {
 	char       *value;
 } epair_t;
 
+/**	In-memory representation of an entity as parsed from the map script.
+*/
 typedef struct {
-	vec3_t      origin;
-	mbrush_t   *brushes;
-	epair_t    *epairs;
+	vec3_t      origin;			///< Location of this entity in world-space.
+	mbrush_t   *brushes;		///< Nul terminated list of brushes.
+	epair_t    *epairs;			///< Nul terminated list of key=value pairs.
 } entity_t;
 
 extern int      nummapbrushes;
@@ -59,15 +61,61 @@ extern entity_t entities[MAX_MAP_ENTITIES];
 extern int      nummiptex;
 extern char     miptex[MAX_MAP_TEXINFO][16];
 
+/**	Load and parse the map script.
+
+	Fills in the ::mapbrushes, ::entities and ::miptex arrays.
+
+	\param filename	Path of the map script to parse.
+*/
 void LoadMapFile (const char *filename);
 
+/**	Allocate a miptex handle for the named miptex.
+
+	If the a miptex with the same name already exists, the previous handle
+	will be returned. \c hint and \c skip textures are handled specially,
+	returning \c TEX_HINT and \c TEX_SKIP respectively.
+
+	\param name		The name of the texture.
+	\return			The handle for the texture.
+*/
 int FindMiptex (const char *name);
 
+/**	Dump an entity's data to stdout.
+
+	\param ent		The entity to dump.
+*/
 void PrintEntity (entity_t *ent);
+
+/**	Get the value for the specified key from an entity.
+
+	\param ent		The entity from which to fetch the value.
+	\param key		The key for which to fetch the value.
+	\return			The value for the key, or the empty string if the key
+					does not exist in this entity.
+*/
 const char *ValueForKey (entity_t *ent, const char *key);
+
+/**	Set the value of the entity's key.
+	If the key does not exist, one will be added.
+
+	\param ent		The entity owning the key.
+	\param key		The key to set.
+	\param value	The value to which the key is to be set.
+*/
 void SetKeyValue (entity_t *ent, const char *key, const char *value);
+
+/**	Parse a vector value from an entity's key.
+	\param ent		The entity from which to fetch the key.
+	\param key		The key of wich to parse the vector value.
+	\param vec		The destination of the vector value.
+*/
 void GetVectorForKey (entity_t *ent, const char *key, vec3_t vec);
 
+/**	Write all valid entities to the bsp file.
+
+	Writes all entities that still have \c key=value pairs to the bsp file.
+	Only the key=value pairs are written: any brush data is left out.
+*/
 void WriteEntitiesToString (void);
 
 #endif//qfbsp_map_h