Fix #423 (Switch from CppDoc to Doxygen), based on patch from anr.

Also delete some unused declarations, and rename is_playing to snd_is_playing. This was SVN commit r7813.
2010-07-29 15:55:41 +00:00 · 2010-07-29 15:55:41 +00:00 · 1706363bab
commit 1706363bab
parent 797e2bb491
67 changed files with 449 additions and 405 deletions
--- a/docs/doxygen/config
+++ b/docs/doxygen/config
@ -3,12 +3,12 @@ PROJECT_NUMBER         = trunk

 TAB_SIZE               = 4

-INPUT                  = ../../source/simulation2 ../../source/scriptinterface ../../source/network ../../source/gui
+INPUT                  = ../../source
 INCLUDE_PATH           = ../../source
 EXAMPLE_PATH           = ../../source
 RECURSIVE              = YES
 EXCLUDE_PATTERNS       = */.svn* */tests/test_*
-EXCLUDE                = ../../source/dcdt ../../source/tools ../../source/i18n/tests2
+EXCLUDE                = ../../source/tools ../../source/i18n/tests2 ../../source/simulation

 JAVADOC_AUTOBRIEF      = YES

@ -23,6 +23,10 @@ GENERATE_LATEX         = NO

 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
-PREDEFINED             = "UNUSED(x)=x"
+PREDEFINED             = "UNUSED(x)=x" \
+                         "METHODDEF(x)=static x" \
+                         "GLOBAL(x)=x"                 
 EXPAND_AS_DEFINED     += DEFAULT_COMPONENT_ALLOCATOR DEFAULT_SCRIPT_WRAPPER DEFAULT_INTERFACE_WRAPPER DEFAULT_MESSAGE_IMPL
-EXPAND_AS_DEFINED     += MESSAGE INTERFACE COMPONENT
+EXPAND_AS_DEFINED     += MESSAGE INTERFACE COMPONENT GUISTDTYPE
+ 
+WARN_LOGFILE           = doxygen.log
--- a/source/collada/CommonConvert.h
+++ b/source/collada/CommonConvert.h
@ -66,7 +66,7 @@ private:

 /**
 * Standard document loader. Based on FCDocument::LoadFromText, but allows
- * access to <extra> nodes at the document level (i.e. directly in <COLLADA>).
+ * access to \<extra\> nodes at the document level (i.e. directly in \<COLLADA\>).
 */
 class FColladaDocument
 {
@ -81,7 +81,7 @@ public:
 	/** Returns the FCDocument that was loaded. */
 	FCDocument* GetDocument() const { return document.get(); }

-	/** Returns the <extra> data from the <COLLADA> element. */
+	/** Returns the \<extra\> data from the \<COLLADA\> element. */
 	FCDExtra* GetExtra() const { return extra.get(); }

 private:
--- a/source/collada/StdSkeletons.h
+++ b/source/collada/StdSkeletons.h
@ -84,9 +84,11 @@ public:
 	/**
 	 * Initialises the global state with skeleton data loaded from the
 	 * given XML data. Must only be called once.
-	 * (TODO: stop using global state.)
+	 * @todo Stop using global state.
+	 * @param xmlData	 
+	 * @param xmlLength
 	 * @param xmlErrors output - XML parser error messages; will be non-empty
-	 * on failure (and failure will always throw)
+	 *		  on failure (and failure will always throw)
 	 * @throws ColladaException on failure
 	 */
 	static void LoadSkeletonDataFromXml(const char* xmlData, size_t xmlLength, std::string& xmlErrors);
--- a/source/graphics/ColladaManager.h
+++ b/source/graphics/ColladaManager.h
@ -36,7 +36,8 @@ public:
 	 * Performs a (cached) conversion from COLLADA if necessary.
 	 *
 	 * @param pathnameNoExtension path and name, minus extension, of file to load.
-	 * One of either "sourceName.pmd" or "sourceName.dae" should exist.
+	 *		  One of either "sourceName.pmd" or "sourceName.dae" should exist.
+	 * @param type FileType, .pmd or .psa
 	 *
 	 * @return full VFS path (including extension) of file to load; or empty
 	 * string if there was a problem and it could not be loaded.
--- a/source/graphics/UnitManager.cpp
+++ b/source/graphics/UnitManager.cpp
@ -125,7 +125,7 @@ CUnit* CUnitManager::PickUnit(const CVector3D& origin, const CVector3D& dir, boo

 ///////////////////////////////////////////////////////////////////////////////
 // CreateUnit: create a new unit and add it to the world
-CUnit* CUnitManager::CreateUnit(const CStrW& actorName, const std::set<CStr>& selections)
+CUnit* CUnitManager::CreateUnit(const CStrW& actorName, const std::set<CStr8>& selections)
 {
 	if (! m_ObjectManager)
 		return NULL;
--- a/source/gui/CGUI.h
+++ b/source/gui/CGUI.h
@ -155,6 +155,7 @@ public:
 	 * @param DefaultColor Color used if no tag applied.
 	 * @param pos position
 	 * @param z z value.
+	 * @param clipping
 	 */
 	void DrawText(SGUIText &Text, const CColor &DefaultColor, 
 				  const CPos &pos, const float &z, const CRect &clipping);
@ -242,10 +243,8 @@ public:
 	 *		  can be changed by tags.
 	 * @param Width Width, 0 if no word-wrapping.
 	 * @param BufferZone space between text and edge, and space between text and images.
-	 *
-	 * pObject is *only* if error parsing fails, and we need to be able to output
-	 * which object the error occured in to aid the user. The parameter is completely
-	 * optional.
+	 * @param pObject Optional parameter for error output. Used *only* if error parsing fails, 
+	 *		  and we need to be able to output which object the error occured in to aid the user. 
 	 */
 	SGUIText GenerateText(const CGUIString &Text, const CStr& Font, 
 						  const float &Width, const float &BufferZone,
@ -370,6 +369,7 @@ private:
 	 * @param Element	The Xeromyces object that represents
 	 *					the objects-tag.
 	 * @param pFile		The Xeromyces object for the file being read
+	 * @param Paths		Collects the set of all XML/JS files that are loaded
 	 *
 	 * @see LoadXmlFile()
 	 */
@ -448,6 +448,7 @@ private:
 	 * @param Element	The Xeromyces object that represents
 	 *					the script-tag.
 	 * @param pFile		The Xeromyces object for the file being read
+	 * @param Paths		Output set of file paths that this script is loaded from.
 	 *
 	 * @see LoadXmlFile()
 	 */
--- a/source/gui/CGUISprite.h
+++ b/source/gui/CGUISprite.h
@ -120,7 +120,7 @@ struct SGUIImage

 /**
 * The GUI sprite, is actually several real sprites (images)
- * like a collage. View the section <sprites> in the GUI
+ * like a collage. View the section \<sprites\> in the GUI
 * TDD for more information.
 *
 * Drawing routine is located in CGUI
--- a/source/gui/CList.h
+++ b/source/gui/CList.h
@ -111,7 +111,7 @@ protected:
 	virtual void SelectLastElement();

 	/**
-	 * Handle the <item> tag.
+	 * Handle the \<item\> tag.
 	 */
 	virtual bool HandleAdditionalChildren(const XMBElement& child, CXeromyces* pFile);

--- a/source/gui/GUIbase.h
+++ b/source/gui/GUIbase.h
@ -67,10 +67,9 @@ public:																	\
 //--------------------------------------------------------
 //  Types
 //--------------------------------------------------------
+
 /** 
- * @enum EGUIMessage
- * Message types
- *
+ * Message types.
 * @see SGUIMessage
 */
 enum EGUIMessageType
--- a/source/gui/GUItext.h
+++ b/source/gui/GUItext.h
@ -291,11 +291,10 @@ public:
 	 * @param from From character n,
 	 * @param to to character n.
 	 * @param FirstLine Whether this is the first line of text, to calculate its height correctly
-	 * 
-	 * pObject Only for Error outputting, optional! If NULL
-	 * then no Errors will be reported! Useful when you need
-	 * to make several GenerateTextCall in different phases,
-	 * it avoids duplicates.
+	 * @param pObject Only for Error outputting, optional! If NULL
+	 *		  then no Errors will be reported! Useful when you need
+	 *		  to make several GenerateTextCall in different phases,
+	 *		  it avoids duplicates.
 	 */
 	void GenerateTextCall(SFeedback &Feedback,
 						  const CStr& DefaultFont,
--- a/source/gui/GUIutil.h
+++ b/source/gui/GUIutil.h
@ -140,7 +140,7 @@ public:
 	/**
 	 * Retrieves a setting by settings name and object name
 	 *
-	 * @param GUI GUI Object const ref
+	 * @param GUIinstance GUI Object const ref
 	 * @param Object Object name
 	 * @param Setting Setting by name
 	 * @param Value Stores value here, note type T!
@ -165,10 +165,11 @@ public:
 	 * This is just a wrapper so that we can type the object name
 	 *  and not input the actual pointer.
 	 *
-	 * @param GUI GUI Object, reference since we'll be changing values
+	 * @param GUIinstance GUI Object, reference since we'll be changing values
 	 * @param Object Object name
 	 * @param Setting Setting by name
 	 * @param Value Sets value to this, note type T!
+	 * @param SkipMessage Does not send a GUIM_SETTINGS_UPDATED if true
 	 */
 	static PSRETURN SetSetting(
 		CGUI &GUIinstance, const CStr& Object, 
--- a/source/gui/IGUIObject.h
+++ b/source/gui/IGUIObject.h
@ -255,13 +255,6 @@ public:
 	 */
 	void CheckSettingsValidity();

-	/**
-	 * Sets up a map_size_t to include the variables in m_BaseSettings
-	 *
-	 * @param SettingsInfo Pointers that should be filled with base variables
-	 */
-	//void SetupBaseSettingsInfo(map_Settings &SettingsInfo);
-
 	/**
 	 * Set a setting by string, regardless of what type it is.
 	 *
@ -269,8 +262,9 @@ public:
 	 *
 	 * @param Setting Setting by name
 	 * @param Value Value to set to
+	 * @param SkipMessage Does not send a GUIM_SETTINGS_UPDATED if true
 	 *
-	 * @return PSERROR (PSRETURN_OK if successful)
+	 * @return PSRETURN (PSRETURN_OK if successful)
 	 */
 	PSRETURN SetSetting(const CStr& Setting, const CStrW& Value, const bool& SkipMessage=false);

@ -413,19 +407,6 @@ protected:
 	 */
 	IGUIObject *GetParent() const;

-	/**
-	 * Same as reference, but returns a const
-	 */
-//	IGUIObject const *GetParent() const;
-
-	/**
-	 * You input the setting struct you want, and it will return a pointer to
-	 * the struct.
-	 *
-	 * @param SettingsStruct tells us which pointer ot return
-	 */
-	//virtual void *GetStructPointer(const EGUISettingsStruct &SettingsStruct) const;
-
 	/**
 	 * Get Mouse from CGUI.
 	 */
@ -500,7 +481,7 @@ private:
 	 *
 	 * @return the error result
 	 */
-	PSRETURN LogInvalidSettings(const CStr& Setting) const;
+	PSRETURN LogInvalidSettings(const CStr8& Setting) const;

 	// Variables

--- a/source/gui/IGUIScrollBar.h
+++ b/source/gui/IGUIScrollBar.h
@ -177,8 +177,7 @@ public:
 	/**
 	 * Hovering the scroll minus button
 	 *
-	 * @param m_x mouse x
-	 * @param m_y mouse y
+	 * @param mouse current mouse position
 	 * @return True if mouse positions are hovering the button
 	 */
 	virtual bool HoveringButtonMinus(const CPos& UNUSED(mouse)) { return false; }
@ -186,8 +185,7 @@ public:
 	/**
 	 * Hovering the scroll plus button
 	 *
-	 * @param m_x mouse x
-	 * @param m_y mouse y
+	 * @param mouse current mouse position
 	 * @return True if mouse positions are hovering the button
 	 */
 	virtual bool HoveringButtonPlus(const CPos& UNUSED(mouse)) { return false; }
@ -200,7 +198,7 @@ public:
 	/**
 	 * Set scroll-position by hand
 	 */
-	virtual void SetPos(const float &f) { m_Pos = f; UpdatePosBoundaries(); }
+	virtual void SetPos(float f) { m_Pos = f; UpdatePosBoundaries(); }

 	/**
 	 * Get the value of Pos that corresponds to the bottom of the scrollable region
@ -249,55 +247,55 @@ public:
 	 * Set Width
 	 * @param width Width
 	 */
-	void SetWidth(const float &width) { m_Width = width; }
+	void SetWidth(float width) { m_Width = width; }
 	
 	/**
 	 * Set X Position
 	 * @param x Position in this axis
 	 */
-	void SetX(const float &x) { m_X = x; }
+	void SetX(float x) { m_X = x; }

 	/**
 	 * Set Y Position
 	 * @param y Position in this axis
 	 */
-	void SetY(const float &y) { m_Y = y; }
+	void SetY(float y) { m_Y = y; }

 	/**
 	 * Set Z Position
 	 * @param z Position in this axis
 	 */
-	void SetZ(const float &z) { m_Z = z; }
+	void SetZ(float z) { m_Z = z; }

 	/**
 	 * Set Length of scroll bar
 	 * @param length Length
 	 */
-	void SetLength(const float &length) { m_Length = length; }
+	void SetLength(float length) { m_Length = length; }

 	/**
 	 * Set content length
 	 * @param range Maximum scrollable range
 	 */
-	void SetScrollRange(const float &range) { m_ScrollRange = std::max(range, 1.f); SetupBarSize(); UpdatePosBoundaries(); }
+	void SetScrollRange(float range) { m_ScrollRange = std::max(range, 1.f); SetupBarSize(); UpdatePosBoundaries(); }

 	/**
 	 * Set space that is visible in the scrollable control.
 	 * @param space Visible area in the scrollable control.
 	 */
-	void SetScrollSpace(const float &space) { m_ScrollSpace = space; SetupBarSize(); UpdatePosBoundaries(); }
+	void SetScrollSpace(float space) { m_ScrollSpace = space; SetupBarSize(); UpdatePosBoundaries(); }

 	/**
 	 * Set bar pressed
-	 * @param pressed True if bar is pressed
+	 * @param b True if bar is pressed
 	 */
-	void SetBarPressed(const bool &b) { m_BarPressed = b; }
+	void SetBarPressed(bool b) { m_BarPressed = b; }

 	/**
 	 * Set use edge buttons
 	 * @param b True if edge buttons should be used
 	 */
-	void SetUseEdgeButtons(const bool &b) { m_UseEdgeButtons = b; }
+	void SetUseEdgeButtons(bool b) { m_UseEdgeButtons = b; }

 	/**
 	 * Set Scroll bar style string
--- a/source/gui/IGUITextOwner.h
+++ b/source/gui/IGUITextOwner.h
@ -82,6 +82,7 @@ public:
 	 * Draws the Text.
 	 *
 	 * @param index Index value of text. Mostly this will be 0
+	 * @param color
 	 * @param pos Position
 	 * @param z Z value
 	 * @param clipping Clipping rectangle, don't even add a parameter
--- a/source/gui/scripting/JSInterface_GUITypes.cpp
+++ b/source/gui/scripting/JSInterface_GUITypes.cpp
@ -21,7 +21,6 @@
 #include "ps/CStr.h"

 /**** GUISize ****/
-
 JSClass JSI_GUISize::JSI_class = {
 	"GUISize", 0,
 		JS_PropertyStub, JS_PropertyStub,
--- a/source/lib/allocators/allocators.h
+++ b/source/lib/allocators/allocators.h
@ -58,8 +58,8 @@ LIB_API void* page_aligned_alloc(size_t unaligned_size);
 /**
 * free a previously allocated page-aligned region.
 *
- * @param p exact value returned from page_aligned_alloc
- * @param size exact value passed to page_aligned_alloc
+ * @param p Exact value returned from page_aligned_alloc
+ * @param unaligned_size Exact value passed to page_aligned_alloc
 **/
 LIB_API void page_aligned_free(void* p, size_t unaligned_size);

@ -133,7 +133,7 @@ extern void matrix_free(void** matrix);
 //-----------------------------------------------------------------------------

 /**
- * Allocate <size> bytes of zeroed memory.
+ * Allocate \<size\> bytes of zeroed memory.
 *
 * intended for applications that frequently alloc/free a single
 * fixed-size object. caller provides static storage and an in-use flag;
@ -143,11 +143,11 @@ extern void matrix_free(void** matrix);
 *
 * note: thread-safe despite use of shared static data.
 *
- * @param storage Caller-allocated memory of at least <size> bytes
+ * @param storage Caller-allocated memory of at least \<size\> bytes
 * (typically a static array of bytes)
- * @param in_use_flag Pointer to a flag we set when <storage> is in-use.
+ * @param in_use_flag Pointer to a flag we set when \<storage\> is in-use.
 * @param size [bytes] to allocate
- * @return allocated memory (typically = <storage>, but falls back to
+ * @return allocated memory (typically = \<storage\>, but falls back to
 * malloc if that's in-use), or 0 (with warning) if out of memory.
 **/
 extern void* single_calloc(void* storage, volatile intptr_t* in_use_flag, size_t size);
@ -157,7 +157,7 @@ extern void* single_calloc(void* storage, volatile intptr_t* in_use_flag, size_t
 *
 * @param storage Exact value passed to single_calloc.
 * @param in_use_flag Exact value passed to single_calloc.
- * @param Exact value returned by single_calloc.
+ * @param p Exact value returned by single_calloc.
 **/
 extern void single_free(void* storage, volatile intptr_t* in_use_flag, void* p);

@ -218,7 +218,7 @@ struct StaticStorage
 	void* end;
 };

-// define <size> bytes of storage and prepare <name> for use with
+// define \<size\> bytes of storage and prepare \<name\> for use with
 // static_calloc.
 // must be invoked from file or function scope.
 #define STATIC_STORAGE(name, size)\
@ -271,7 +271,7 @@ CONFIG2_ALLOCATORS_OVERRUN_PROTECTION == 1; this avoids having to remove the
 wrapper code in release builds and re-write when looking for overruns.

 example usage:
-OverrunProtector<your_class> your_class_wrapper;
+OverrunProtector\<your_class\> your_class_wrapper;
 ..
 your_class* yc = your_class_wrapper.get();	// unlock, make ready for use
 if(!yc)			// your_class_wrapper's one-time alloc of a your_class-
--- a/source/lib/allocators/bucket.h
+++ b/source/lib/allocators/bucket.h
@ -69,7 +69,7 @@ struct Bucket
 /**
 * ready the Bucket object for use.
 *
- * @param Bucket*
+ * @param b Bucket*
 * @param el_size 0 to allow variable-sized allocations (which cannot be
 * freed individually); otherwise, it specifies the number of bytes that
 * will be returned by bucket_alloc (whose size parameter is then ignored).
@ -78,11 +78,11 @@ struct Bucket
 LIB_API LibError bucket_create(Bucket* b, size_t el_size);

 /**
- * free all memory that ensued from <b>.
+ * free all memory that ensued from \<b\>.
 *
 * future alloc and free calls on this Bucket will fail.
 *
- * @param Bucket*
+ * @param b Bucket*
 **/
 LIB_API void bucket_destroy(Bucket* b);

@ -90,7 +90,7 @@ LIB_API void bucket_destroy(Bucket* b);
 * Dole out memory from the Bucket.
 * exhausts the freelist before returning new entries to improve locality.
 *
- * @param Bucket*
+ * @param b Bucket*
 * @param size bytes to allocate; ignored if bucket_create's el_size was not 0.
 * @return allocated memory, or 0 if the Bucket would have to be expanded and
 * there isn't enough memory to do so.
@ -106,7 +106,7 @@ LIB_API void* bucket_fast_alloc(Bucket* b);
 * rationale: avoids having to pass el_size here and compare with size when
 * allocating; also prevents fragmentation and leaking memory.
 *
- * @param Bucket*
+ * @param b Bucket*
 * @param el entry allocated via bucket_alloc.
 **/
 LIB_API void bucket_free(Bucket* b, void* el);
--- a/source/lib/allocators/dynarray.h
+++ b/source/lib/allocators/dynarray.h
@ -69,7 +69,7 @@ LIB_API LibError da_alloc(DynArray* da, size_t max_size);
 *
 * use-after-free is impossible because the memory is unmapped.
 *
- * @param DynArray* da; zeroed afterwards.
+ * @param da DynArray* zeroed afterwards.
 * @return LibError
 **/
 LIB_API LibError da_free(DynArray* da);
@ -86,10 +86,10 @@ LIB_API LibError da_free(DynArray* da);
 LIB_API LibError da_set_size(DynArray* da, size_t new_size);

 /**
- * Make sure at least <size> bytes starting at da->pos are committed and
+ * Make sure at least \<size\> bytes starting at da->pos are committed and
 * ready for use.
 *
- * @param DynArray*
+ * @param da DynArray*
 * @param size Minimum amount to guarantee [bytes]
 * @return LibError
 **/
--- a/source/lib/allocators/pool.h
+++ b/source/lib/allocators/pool.h
@ -56,7 +56,7 @@ struct Pool
 };

 /**
- * pass as pool_create's <el_size> param to indicate variable-sized allocs
+ * pass as pool_create's \<el_size\> param to indicate variable-sized allocs
 * are required (see below).
 **/
 const size_t POOL_VARIABLE_ALLOCS = ~(size_t)0u;
@ -64,7 +64,7 @@ const size_t POOL_VARIABLE_ALLOCS = ~(size_t)0u;
 /**
 * Ready Pool for use.
 *
- * @param Pool*
+ * @param p Pool*
 * @param max_size Max size [bytes] of the Pool; this much
 * (rounded up to next page multiple) virtual address space is reserved.
 * no virtual memory is actually committed until calls to pool_alloc.
@ -84,7 +84,7 @@ LIB_API LibError pool_create(Pool* p, size_t max_size, size_t el_size);
 * impossible because it is marked not-present via MMU.
 * (* no matter if in freelist or unused or "allocated" to user)
 *
- * @param Pool*
+ * @param p Pool*
 * @return LibError.
 **/
 LIB_API LibError pool_destroy(Pool* p);
@ -94,7 +94,8 @@ LIB_API LibError pool_destroy(Pool* p);
 *
 * this is useful for callers that use several types of allocators.
 *
- * @param Pool*
+ * @param p Pool*
+ * @param el
 * @return bool.
 **/
 LIB_API bool pool_contains(const Pool* p, void* el);
@ -103,7 +104,7 @@ LIB_API bool pool_contains(const Pool* p, void* el);
 * Dole out memory from the pool.
 * exhausts the freelist before returning new entries to improve locality.
 *
- * @param Pool*
+ * @param p Pool*
 * @param size bytes to allocate; ignored if pool_create's el_size was not 0.
 * @return allocated memory, or 0 if the Pool would have to be expanded and
 * there isn't enough memory to do so.
@ -117,7 +118,7 @@ LIB_API void* pool_alloc(Pool* p, size_t size);
 * rationale: avoids having to pass el_size here and compare with size when
 * allocating; also prevents fragmentation and leaking memory.
 *
- * @param Pool*
+ * @param p Pool*
 * @param el Element returned by pool_alloc.
 **/
 LIB_API void pool_free(Pool* p, void* el);
@ -128,7 +129,7 @@ LIB_API void pool_free(Pool* p, void* el);
 * this resets it as if freshly pool_create-d, but doesn't release the
 * underlying reserved virtual memory.
 *
- * @param Pool*
+ * @param p Pool*
 **/
 LIB_API void pool_free_all(Pool* p);

--- a/source/lib/base32.h
+++ b/source/lib/base32.h
@ -30,9 +30,9 @@
 /**
 * generate the base32 textual representation of a buffer.
 *
- * @param len size [bytes] of input
- * @param big-endian input data (assumed to be integral number of bytes)
- * @param output string; zero-terminated. must be big enough
+ * @param len Size [bytes] of input
+ * @param in Big-endian input data (assumed to be integral number of bytes)
+ * @param out Output string; zero-terminated. must be big enough
 * (i.e. at least ceil(len*CHAR_BIT/5) + 1 chars)
 **/
 extern void base32(const size_t len, const u8* in, u8* out);
--- a/source/lib/bits.h
+++ b/source/lib/bits.h
@ -28,7 +28,7 @@
 #define INCLUDED_BITS

 /**
- * value of bit number <n>.
+ * value of bit number \<n\>.
 *
 * @param n bit index.
 *
@ -44,13 +44,12 @@ T Bit(size_t n)
 }

 /**
- * pretty much the same as Bit<unsigned>.
+ * pretty much the same as Bit\<unsigned\>.
 * this is intended for the initialization of enum values, where a
 * compile-time constant is required.
 **/
 #define BIT(n) (1u << (n))

-
 template<typename T>
 bool IsBitSet(T value, size_t index)
 {
@ -67,7 +66,7 @@ bool IsBitSet(T value, size_t index)
 /**
 * a mask that includes the lowest N bits
 *
- * @param num_bits number of bits in mask
+ * @param numBits Number of bits in mask.
 **/
 template<typename T>
 T bit_mask(size_t numBits)
@ -162,7 +161,7 @@ size_t ceil_log2(T x)
 * floor(log2(f))
 * fast, uses the FPU normalization hardware.
 *
- * @param f (float) input; MUST be > 0, else results are undefined.
+ * @param x (float) input; MUST be > 0, else results are undefined.
 * @return floor of the base-2 logarithm (i.e. rounded down).
 **/
 extern int floor_log2(const float x);
@ -179,7 +178,8 @@ T round_up_to_pow2(T x)
 /**
 * round number up/down to the next given multiple.
 *
- * @param multiple: must be a power of two.
+ * @param n Number to round.
+ * @param multiple Must be a power of two.
 **/
 template<typename T>
 T round_up(T n, T multiple)
--- a/source/lib/byte_order.h
+++ b/source/lib/byte_order.h
@ -113,15 +113,15 @@ LIB_API void write_be32(void* p, u32 x);	/// see write_be16
 LIB_API void write_be64(void* p, u64 x);	/// see write_be16

 /**
- * zero-extend <size> (truncated to 8) bytes of little-endian data to u64,
- * starting at address <p> (need not be aligned).
+ * zero-extend \<size\> (truncated to 8) bytes of little-endian data to u64,
+ * starting at address \<p\> (need not be aligned).
 **/
 LIB_API u64 movzx_le64(const u8* p, size_t size);
 LIB_API u64 movzx_be64(const u8* p, size_t size);

 /**
- * sign-extend <size> (truncated to 8) bytes of little-endian data to i64,
- * starting at address <p> (need not be aligned).
+ * sign-extend \<size\> (truncated to 8) bytes of little-endian data to i64,
+ * starting at address \<p\> (need not be aligned).
 **/
 LIB_API i64 movsx_le64(const u8* p, size_t size);
 LIB_API i64 movsx_be64(const u8* p, size_t size);
--- a/source/lib/code_annotation.h
+++ b/source/lib/code_annotation.h
@ -124,13 +124,13 @@ switch(x % 2)
 #define UID2__ PASTE3__(LINE_, __LINE__, _2)

 /**
- * compile-time debug_assert. causes a compile error if the expression
+ * Compile-time debug_assert. Causes a compile error if the expression
 * evaluates to zero/false.
 *
- * no runtime overhead; may be used anywhere, including file scope.
- * especially useful for testing sizeof types.
+ * No runtime overhead; may be used anywhere, including file scope.
+ * Especially useful for testing sizeof types.
 *
- * @param expression that is expected to evaluate to non-zero at compile-time.
+ * @param expr Expression that is expected to evaluate to non-zero at compile-time.
 **/
 #define cassert(expr) typedef static_assert_<(expr)>::type UID__
 template<bool> struct static_assert_;
@ -140,16 +140,10 @@ template<> struct static_assert_<true>
 };

 /**
- * compile-time debug_assert. causes a compile error if the expression
- * evaluates to zero/false.
+ * @copydoc cassert(expr)
 *
- * no runtime overhead; may be used anywhere, including file scope.
- * especially useful for testing sizeof types.
- *
- * this version has a less helpful error message, but redefinition doesn't
+ * This version has a less helpful error message, but redefinition doesn't
 * trigger warnings.
- *
- * @param expression that is expected to evaluate to non-zero at compile-time.
 **/
 #define cassert2(expr) extern u8 CASSERT_FAILURE[1][(expr)]

--- a/source/lib/debug.h
+++ b/source/lib/debug.h
@ -66,7 +66,7 @@ extern void debug_break();
 * write a formatted string to the debug channel, subject to filtering
 * (see below). implemented via debug_puts - see performance note there.
 *
- * @param format string and varargs; see printf.
+ * @param fmt Format string and varargs; see printf.
 **/
 LIB_API void debug_printf(const wchar_t* fmt, ...) WPRINTF_ARGS(1);

@ -189,7 +189,7 @@ LIB_API ErrorReaction debug_DisplayError(const wchar_t* description, size_t flag
 * depending on "debug level", because changing that entails lengthy
 * compiles and it's too coarse-grained. instead, we require all
 * strings to start with "tag_string|" (exact case and no quotes;
- * the alphanumeric-only <tag_string> identifies output type).
+ * the alphanumeric-only \<tag_string\> identifies output type).
 * they are then subject to filtering: only if the tag has been
 * "added" via debug_filter_add is the appendant string displayed.
 *
@ -232,7 +232,7 @@ LIB_API bool debug_filter_allows(const wchar_t* text);
 * write to memory buffer (fast)
 * used for "last activity" reporting in the crashlog.
 *
- * @param format string and varags; see printf.
+ * @param fmt Format string and varags; see printf.
 **/
 LIB_API void debug_wprintf_mem(const wchar_t* fmt, ...) WPRINTF_ARGS(1);

@ -254,7 +254,7 @@ LIB_API LibError debug_WriteCrashlog(const wchar_t* text);
 //-----------------------------------------------------------------------------

 /**
- * make sure the expression <expr> evaluates to non-zero. used to validate
+ * make sure the expression \<expr\> evaluates to non-zero. used to validate
 * invariants in the program during development and thus gives a
 * very helpful warning if something isn't going as expected.
 * sprinkle these liberally throughout your code!
@ -268,7 +268,7 @@ LIB_API LibError debug_WriteCrashlog(const wchar_t* text);
 * - consistency (everything here is prefixed with debug_) and
 * - to avoid inadvertent use of the much less helpful built-in CRT assert.
 *   if we were to override assert, it would be difficult to tell whether
- *   user source has included <assert.h> (possibly indirectly via other
+ *   user source has included \<assert.h\> (possibly indirectly via other
 *   headers) and thereby stomped on our definition.
 **/
 #define debug_assert(expr) \
@ -338,7 +338,7 @@ STMT(\
 * notifies the user via debug_DisplayError.
 *
 * @param assert_expr the expression that failed; typically passed as
- * #expr in the assert macro.
+ * \#expr in the assert macro.
 * @param suppress see debug_DisplayError.
 * @param file, line source file name and line number of the spot that failed
 * @param func name of the function containing it
@ -408,7 +408,7 @@ namespace INFO


 /**
- * maximum number of characters (including trailing \0) written to
+ * Maximum number of characters (including trailing \\0) written to
 * user's buffers by debug_ResolveSymbol.
 **/
 const size_t DBG_SYMBOL_LEN = 1000;
@ -438,19 +438,19 @@ LIB_API LibError debug_ResolveSymbol(void* ptr_of_interest, wchar_t* sym_name, w
 * write a complete stack trace (including values of local variables) into
 * the specified buffer.
 *
- * @param buf target buffer
- * @param max_chars of buffer (should be several thousand)
- * @param context platform-specific representation of execution state
- * (e.g. Win32 CONTEXT). if not NULL, tracing starts there; this is useful
- * for exceptions. otherwise, tracing starts from the current call stack.
- * @param lastFuncToSkip is used for omitting error-reporting functions like
- * debug_OnAssertionFailure from the stack trace. it is either 0 (skip nothing) or
- * a substring of a function's name (this allows platform-independent
- * matching of stdcall-decorated names).
- * rationale: this is safer than specifying a fixed number of frames,
- * which can be incorrect due to inlining.
+ * @param buf Target buffer.
+ * @param maxChars Max chars of buffer (should be several thousand).
+ * @param context Platform-specific representation of execution state
+ *		  (e.g. Win32 CONTEXT). if not NULL, tracing starts there; this is useful
+ *		  for exceptions. Otherwise, tracing starts from the current call stack.
+ * @param lastFuncToSkip Is used for omitting error-reporting functions like
+ *		  debug_OnAssertionFailure from the stack trace. It is either 0 (skip nothing) or
+ *		  a substring of a function's name (this allows platform-independent
+ *		  matching of stdcall-decorated names).
+ *		  Rationale: this is safer than specifying a fixed number of frames,
+ *		  which can be incorrect due to inlining.
 * @return LibError; ERR::REENTERED if reentered via recursion or
- * multithreading (not allowed since static data is used).
+ *		   multithreading (not allowed since static data is used).
 **/
 LIB_API LibError debug_DumpStack(wchar_t* buf, size_t maxChars, void* context, const wchar_t* lastFuncToSkip);

@ -524,7 +524,7 @@ struct ErrorMessageMem
 /**
 * free memory from the error message.
 *
- * @param ErrorMessageMem*
+ * @param emm ErrorMessageMem*
 **/
 LIB_API void debug_FreeErrorMessage(ErrorMessageMem* emm);

--- a/source/lib/debug_stl.h
+++ b/source/lib/debug_stl.h
@ -40,12 +40,12 @@ namespace ERR
 * reduce complicated STL symbol names to human-readable form.
 *
 * algorithm: remove/replace undesired substrings in one pass (fast).
- * example: "std::basic_string<char, char_traits<char>,
- * std::allocator<char> >" => "string".
+ * example: "std::basic_string\<char, char_traits\<char\>,
+ * std::allocator\<char\> \>" => "string".
 *
- * @param buffer holding input symbol name; modified in-place.
- * there is no length limit; must be large enough to hold typical STL
- * strings. DBG_SYMBOL_LEN chars is a good measure.
+ * @param name Buffer holding input symbol name; modified in-place.
+ *		  There is no length limit; must be large enough to hold typical STL
+ *		  strings. DBG_SYMBOL_LEN chars is a good measure.
 * @return name for convenience.
 **/
 extern wchar_t* debug_stl_simplify_name(wchar_t* name);
--- a/source/lib/file/archive/archive_zip.cpp
+++ b/source/lib/file/archive/archive_zip.cpp
@ -422,8 +422,10 @@ public:

 private:
 	/**
-	 * scan buffer for a Zip file record.
+	 * Scan buffer for a Zip file record.
 	 *
+	 * @param buf
+	 * @param size
 	 * @param start position within buffer
 	 * @param magic signature of record
 	 * @param recordSize size of record (including signature)
--- a/source/lib/file/archive/codec.h
+++ b/source/lib/file/archive/codec.h
@ -58,17 +58,21 @@ public:
 	/**
 	 * process (i.e. compress or decompress) data.
 	 *
-	 * @param outSize bytes remaining in the output buffer; shall not be zero.
-	 * @param inConsumed, outProduced how many bytes in the input and
-	 * output buffers were used. either or both of these can be zero if
-	 * the input size is small or there's not enough output space.
+	 * @param in
+	 * @param inSize
+	 * @param out
+	 * @param outSize Bytes remaining in the output buffer; shall not be zero.
+	 * @param inConsumed,outProduced How many bytes in the input and
+	 *		  output buffers were used. either or both of these can be zero if
+	 *		  the input size is small or there's not enough output space.
 	 **/
 	virtual LibError Process(const u8* in, size_t inSize, u8* out, size_t outSize, size_t& inConsumed, size_t& outProduced) = 0;

 	/**
-	 * flush buffers and make sure all output has been produced.
+	 * Flush buffers and make sure all output has been produced.
 	 *
-	 * @param checksum over all input data.
+	 * @param checksum Checksum over all input data.
+	 * @param outProduced
 	 * @return error status for the entire operation.
 	 **/
 	virtual LibError Finish(u32& checksum, size_t& outProduced) = 0;
@ -77,6 +81,8 @@ public:
 	 * update a checksum to reflect the contents of a buffer.
 	 *
 	 * @param checksum the initial value (must be 0 on first call)
+	 * @param in
+	 * @param inSize
 	 * @return the new checksum. note: after all data has been seen, this is
 	 * identical to the what Finish would return.
 	 **/
--- a/source/lib/file/common/trace.h
+++ b/source/lib/file/common/trace.h
@ -108,7 +108,7 @@ struct ITrace
 	/**
 	 * load entries from file.
 	 *
-	 * @param pathname (native, absolute)
+	 * @param osPathname (native, absolute)
 	 *
 	 * replaces any existing entries.
 	 **/
--- a/source/lib/file/file_system_util.h
+++ b/source/lib/file/file_system_util.h
@ -59,25 +59,29 @@ enum DirFlags
 /**
 * call back for each file in a directory tree
 *
- * @param cb see DirCallback
+ * @param fs
+ * @param path
+ * @param cb See DirCallback
+ * @param cbData
 * @param pattern that file names must match. '*' and '&' wildcards
- * are allowed. 0 matches everything.
- * @param flags see DirFlags
- * @param LibError
+ *		  are allowed. 0 matches everything.
+ * @param flags @ref DirFlags
+ * @return LibError
 **/
 extern LibError ForEachFile(const PIVFS& fs, const VfsPath& path, FileCallback cb, uintptr_t cbData, const wchar_t* pattern = 0, size_t flags = 0);


 /**
- * determine the next available pathname with a given format.
- * this is useful when creating new files without overwriting the previous
+ * Determine the next available pathname with a given format.
+ * This is useful when creating new files without overwriting the previous
 * ones (screenshots are a good example).
 *
- * @param pathnameFormat format string for the pathname; must contain one
- * format specifier for an integer.
- * example: "screenshots/screenshot%04d.png"
+ * @param fs
+ * @param pathnameFormat Format string for the pathname; must contain one
+ *		  format specifier for an integer.
+ *		  Example: "screenshots/screenshot%04d.png"
 * @param nextNumber in: the first number to try; out: the next number.
- * if 0, numbers corresponding to existing files are skipped.
+ *		  If 0, numbers corresponding to existing files are skipped.
 * @param nextPathname receives the output.
 **/
 extern void NextNumberedFilename(const PIVFS& fs, const VfsPath& pathnameFormat, size_t& nextNumber, VfsPath& nextPathname);
--- a/source/lib/file/io/block_cache.h
+++ b/source/lib/file/io/block_cache.h
@ -64,11 +64,12 @@ public:
 	/**
 	 * Add a block to the cache.
 	 *
-	 * @param id key that will be used to Retrieve the block.
+	 * @param id Key that will be used to Retrieve the block.
+	 * @param buf
 	 *
-	 * call this when the block's IO has completed; its data will
+	 * Call this when the block's IO has completed; its data will
 	 * satisfy subsequent Retrieve calls for the same id.
-	 * if CONFIG2_CACHE_READ_ONLY, the memory is made read-only.
+	 * If CONFIG2_CACHE_READ_ONLY, the memory is made read-only.
 	 **/
 	void Add(BlockId id, const shared_ptr<u8>& buf);

--- a/source/lib/file/vfs/file_cache.h
+++ b/source/lib/file/vfs/file_cache.h
@ -68,14 +68,16 @@ public:
 	/**
 	 * Add a file's contents to the cache.
 	 *
-	 * the cache will be able to satisfy subsequent Retrieve() calls by
+	 * The cache will be able to satisfy subsequent Retrieve() calls by
 	 * returning this data; if CONFIG2_CACHE_READ_ONLY, the buffer is made
-	 * read-only. if need be and no references are currently attached to it,
+	 * read-only. If need be and no references are currently attached to it,
 	 * the memory can also be commandeered by Reserve().
 	 *
+	 * @param data
+	 * @param size
 	 * @param pathname key that will be used to Retrieve file contents.
 	 * @param cost is the expected cost of retrieving the file again and
-	 * influences how/when it is evicted from the cache.
+	 *		  influences how/when it is evicted from the cache.
 	 **/
 	void Add(const VfsPath& pathname, const shared_ptr<u8>& data, size_t size, size_t cost = 1);

--- a/source/lib/file/vfs/vfs.h
+++ b/source/lib/file/vfs/vfs.h
@ -69,6 +69,8 @@ struct IVFS
 	 *
 	 * @param mountPoint (will be created if it does not already exist)
 	 * @param path real directory path
+	 * @param flags
+	 * @param priority
 	 * @return LibError.
 	 *
 	 * if files are encountered that already exist in the VFS (sub)directories,
@ -80,21 +82,22 @@ struct IVFS
 	virtual LibError Mount(const VfsPath& mountPoint, const fs::wpath& path, size_t flags = 0, size_t priority = 0) = 0;

 	/**
-	 * retrieve information about a file (similar to POSIX stat)
+	 * Retrieve information about a file (similar to POSIX stat).
 	 *
-	 * @param pfileInfo receives information about the file. passing NULL
-	 * suppresses warnings if the file doesn't exist.
+	 * @param pathname
+	 * @param pfileInfo receives information about the file. Passing NULL
+	 *		  suppresses warnings if the file doesn't exist.
 	 * 
 	 * @return LibError.
 	 **/
 	virtual LibError GetFileInfo(const VfsPath& pathname, FileInfo* pfileInfo) const = 0;

 	/**
-	 * retrieve lists of all files and subdirectories in a directory.
+	 * Retrieve lists of all files and subdirectories in a directory.
 	 *
 	 * @return LibError.
 	 *
-	 * rationale:
+	 * Rationale:
 	 * - this interface avoids having to lock the directory while an
 	 *   iterator is extant.
 	 * - we cannot efficiently provide routines for returning files and
@ -103,8 +106,9 @@ struct IVFS
 	virtual LibError GetDirectoryEntries(const VfsPath& path, FileInfos* fileInfos, DirectoryNames* subdirectoryNames) const = 0;

 	/**
-	 * create a file with the given contents.
-	 *
+	 * Create a file with the given contents.
+	 * @param pathname
+	 * @param fileContents
 	 * @param size [bytes] of the contents, will match that of the file.
 	 * @return LibError.
 	 *
@ -114,13 +118,14 @@ struct IVFS
 	virtual LibError CreateFile(const VfsPath& pathname, const shared_ptr<u8>& fileContents, size_t size) = 0;

 	/**
-	 * read an entire file into memory.
+	 * Read an entire file into memory.
 	 *
+	 * @param pathname
 	 * @param fileContents receives a smart pointer to the contents.
-	 *   CAVEAT: this will be taken from the file cache if the VFS was
-	 *   created with cacheSize != 0 and size < cacheSize. there is no
-	 *   provision for Copy-on-Write, which means that such buffers
-	 *   must not be modified (this is enforced via mprotect).
+	 *		  CAVEAT: this will be taken from the file cache if the VFS was
+	 * 		  created with cacheSize != 0 and size < cacheSize. There is no
+	 * 		  provision for Copy-on-Write, which means that such buffers
+	 * 		  must not be modified (this is enforced via mprotect).
 	 * @param size receives the size [bytes] of the file contents.
 	 * @return LibError.
 	 **/
--- a/source/lib/file/vfs/vfs_lookup.h
+++ b/source/lib/file/vfs/vfs_lookup.h
@ -49,11 +49,11 @@ enum VfsLookupFlags
 * Resolve a pathname.
 *
 * @param pathname
- * @param vfsStartDirectory
+ * @param startDirectory VfsStartDirectory.
 * @param directory is set to the last directory component that is encountered.
- * @param file is set to 0 if there is no name component, otherwise the
- * corresponding file.
- * @param flags see VfsLookupFlags.
+ * @param pfile File is set to 0 if there is no name component, otherwise the
+ *		  corresponding file.
+ * @param flags @see VfsLookupFlags.
 * @return LibError (INFO::OK if all components in pathname exist).
 *
 * to allow noiseless file-existence queries, this does not raise warnings.
--- a/source/lib/path_util.h
+++ b/source/lib/path_util.h
@ -70,11 +70,11 @@ LIB_API bool path_is_dir_sep(wchar_t c);
 LIB_API bool path_is_subpath(const wchar_t* s1, const wchar_t* s2);

 /**
- * get the name component of a path.
+ * Get the name component of a path.
+ * Skips over all characters up to the last dir separator, if any.
 *
- * skips over all characters up to the last dir separator, if any.
- * @param path input path.
- * @return pointer to name component within <path>.
+ * @param path Input path.
+ * @return pointer to name component within \<path\>.
 **/
 LIB_API const wchar_t* path_name_only(const wchar_t* path);

--- a/source/lib/res/graphics/cursor.h
+++ b/source/lib/res/graphics/cursor.h
@ -30,16 +30,17 @@
 #include "lib/file/vfs/vfs.h"

 /**
- * draw the cursor on-screen.
+ * Draw the cursor on-screen.
 *
- * @param name base name of cursor or zero to hide the cursor.
- * @param x,y coordinates [pixels] (origin at lower left)
- * (the origin is convenient for drawing via OpenGL, but requires the
- * mouse Y coordinate to be subtracted from the client area height.
- * making the caller responsible for this avoids a dependency on
- * the g_yres global variable.)
+ * @param vfs
+ * @param name Base name of cursor or zero to hide the cursor.
+ * @param x,y Coordinates [pixels] (origin at lower left)
+ *		  (the origin is convenient for drawing via OpenGL, but requires the
+ *		  mouse Y coordinate to be subtracted from the client area height.
+ *		  Making the caller responsible for this avoids a dependency on
+ *		  the g_yres global variable.)
 *
- * uses a hardware mouse cursor where available, otherwise a
+ * Uses a hardware mouse cursor where available, otherwise a
 * portable OpenGL implementation.
 **/
 extern LibError cursor_draw(const PIVFS& vfs, const wchar_t* name, int x, int y);
--- a/source/lib/res/graphics/ogl_shader.h
+++ b/source/lib/res/graphics/ogl_shader.h
@ -54,8 +54,9 @@ extensions are available, or all bets are off.
 /**
 * Create, load and compile a shader object.
 *
- * @param pathname location of the file containing the shader's source code.
- * @param type e.g. GL_VERTEX_SHADER_ARB.
+ * @param vfs
+ * @param pathname Location of the file containing the shader's source code.
+ * @param type Type e.g. GL_VERTEX_SHADER_ARB.
 **/
 Handle ogl_shader_load(const PIVFS& vfs, const VfsPath& pathname, GLenum type);

@ -78,6 +79,7 @@ Encapsulate program objects into handles.
 /**
 * Load a program object.
 *
+ * @param vfs
 * @param pathname XML file describing the program.
 *
 * note: Shader objects are loaded and attached automatically.
--- a/source/lib/res/graphics/ogl_tex.h
+++ b/source/lib/res/graphics/ogl_tex.h
@ -216,6 +216,8 @@ extern void ogl_tex_set_defaults(int q_flags, GLint filter);
 /**
 * Load and return a handle to the texture.
 *
+* @param vfs
+* @param pathname
 * @param flags h_alloc flags.
 * @return Handle to texture or negative LibError
 * for a list of supported formats, see tex.h's tex_load.
@ -226,7 +228,7 @@ extern Handle ogl_tex_load(const PIVFS& vfs, const VfsPath& pathname, size_t fla
 * Find and return an existing texture object, if it has already been
 * loaded and is still in memory.
 *
-* @param fn VFS filename of texture.
+* @param pathname fn VFS filename of texture.
 * @return Handle to texture or negative LibError
 */
 extern Handle ogl_tex_find(const VfsPath& pathname);
@ -237,9 +239,11 @@ extern Handle ogl_tex_find(const VfsPath& pathname);
 * had been loaded by ogl_tex_load.
 *
 * @param t Texture object.
-* @param fn filename or description of texture. not strictly needed,
+* @param vfs
+* @param pathname filename or description of texture. not strictly needed,
 *        but would allow h_filename to return meaningful info for
 *        purposes of debugging.
+* @param flags
 * @return Handle to texture or negative LibError
 *
 * note: because we cannot guarantee that callers will pass distinct
@ -272,6 +276,7 @@ extern LibError ogl_tex_free(Handle& ht);
 * Override default filter (see {@link #ogl_tex_set_defaults}) for
 * this texture.
 *
+* @param ht Texture handle
 * @param filter OpenGL minification and magnification filter
 *        (rationale: see {@link OglTexState})
 * @return LibError
@ -283,6 +288,7 @@ extern LibError ogl_tex_set_filter(Handle ht, GLint filter);
 /**
 * Override default wrap mode (GL_REPEAT) for this texture.
 *
+* @param ht Texture handle
 * @param wrap OpenGL wrap mode (for both S and T coordinates)
 *        (rationale: see {@link OglTexState})
 * @return LibError
@ -312,26 +318,26 @@ enum OglTexAllow
 * Override the default decision and force/disallow use of the
 * given feature. Typically called from ah_override_gl_upload_caps.
 *
-* @param what feature to influence
-* @param allow disable/enable flag
+* @param what Feature to influence.
+* @param allow Disable/enable flag.
 */
 extern void ogl_tex_override(OglTexOverrides what, OglTexAllow allow);

 /**
 * Upload texture to OpenGL.
 *
+* @param ht Texture handle
 * @param fmt_ovr optional override for OpenGL format (e.g. GL_RGB),
 *        which is decided from bpp / Tex flags
 * @param q_flags_ovr optional override for global default
 *        OglTexQualityFlags
 * @param int_fmt_ovr optional override for OpenGL internal format
 *        (e.g. GL_RGB8), which is decided from fmt / q_flags.
-* @return LibError
+* @return LibError.
+*
 * Side Effects:
-* <UL>
-*   <LI>enables texturing on TMU 0 and binds the texture to it;
-*   <LI>frees the texel data! see ogl_tex_get_data.
-* </UL>
+* - enables texturing on TMU 0 and binds the texture to it;
+* - frees the texel data! see ogl_tex_get_data.
 */
 extern LibError ogl_tex_upload(const Handle ht, GLenum fmt_ovr = 0, int q_flags_ovr = 0, GLint int_fmt_ovr = 0);

@ -404,8 +410,8 @@ extern LibError ogl_tex_bind(Handle ht, size_t unit = 0);
 /**
 * (partially) Transform pixel format of the texture.
 *
-* @param ht Texture handle
-* @param flags the TexFlags that are to be <em>changed</em>
+* @param ht Texture handle.
+* @param flags the TexFlags that are to be @em changed.
 * @return LibError
 * @see tex_transform
 *
@ -416,8 +422,8 @@ extern LibError ogl_tex_transform(Handle ht, size_t flags);
 /**
 * Transform pixel format of the texture.
 *
-* @param ht Texture handle
-* @param flags desired new TexFlags indicating pixel format.
+* @param ht Texture handle.
+* @param new_flags Flags desired new TexFlags indicating pixel format.
 * @return LibError
 * @see tex_transform
 *
@ -431,7 +437,7 @@ extern LibError ogl_tex_transform_to(Handle ht, size_t new_flags);
 * Return whether native S3TC texture compression support is available.
 * If not, textures will be decompressed automatically, hurting performance.
 *
- * @return true if native S3TC supported
+ * @return true if native S3TC supported.
 *
 * ogl_tex_upload must be called at least once before this.
 */
--- a/source/lib/res/graphics/unifont.h
+++ b/source/lib/res/graphics/unifont.h
@ -35,8 +35,10 @@
 /**
 * Load a font.
 *
+ * @param vfs
 * @param pathname path and basename of the font definition file
- * (.fnt) and its texture (.png)
+ *		  (.fnt) and its texture (.png)
+ * @param flags
 **/
 extern Handle unifont_load(const PIVFS& vfs, const VfsPath& pathname, size_t flags = 0);

@ -69,16 +71,20 @@ extern LibError unifont_bind(Handle h);
 extern void glwprintf(const wchar_t* fmt, ...) WPRINTF_ARGS(1);

 /**
- * varargs version of glwprintf.
+ * Varargs version of glwprintf.
 *
- * @param fmt, args - see vfprintf
+ * @param fmt
+ * @param args
+ * @see vfprintf
 **/
 extern void glvwprintf(const wchar_t* fmt, va_list args) VWPRINTF_ARGS(1);

 /**
 * Determine pixel extents of a string.
 *
+ * @param h
 * @param text string in question.
+ * @param width
 * @param height is roughly the pixel height of a capital letter, for use
 * when aligning text in an aesthetically pleasing way.
 *
--- a/source/lib/res/sound/snd_mgr.cpp
+++ b/source/lib/res/sound/snd_mgr.cpp
@ -899,12 +899,14 @@ static LibError SndData_to_string(const SndData* sd, wchar_t* buf)


 /**
- * open and return a handle to a sound file's data.
+ * Open and return a handle to a sound file's data.
 *
+ * @param vfs
+ * @param pathname
 * @param is_stream (default false) indicates whether this file should be
- * streamed in (opening is faster, it won't be kept in memory, but
- * only one instance can be open at a time; makes sense for large music files)
- * or loaded immediately.
+ *		  streamed in (opening is faster, it won't be kept in memory, but
+ *		  only one instance can be open at a time; makes sense for large music files)
+ *		  or loaded immediately.
 * @return Handle or LibError on failure
 */
 static Handle snd_data_load(const PIVFS& vfs, const VfsPath& pathname, bool is_stream)
@ -915,7 +917,6 @@ static Handle snd_data_load(const PIVFS& vfs, const VfsPath& pathname, bool is_s
 }


-
 /**
 * Free the sound.
 *
@ -1160,7 +1161,7 @@ static FadeRet fade(FadeInfo& fi, double cur_time, float& out_val)
 /**
 * Is the fade operation currently active?
 *
- * @param FadeInfo
+ * @param fi FadeInfo.
 * @return bool
 */
 static bool fade_is_active(FadeInfo& fi)
@ -1327,9 +1328,10 @@ static LibError VSrc_to_string(const VSrc* vs, wchar_t* buf)


 /**
- * open and return a handle to a sound instance.
+ * Open and return a handle to a sound instance.
 *
- * @param pathname. if a text file (extension ".txt"),
+ * @param vfs 
+ * @param pathname If a text file (extension ".txt"),
 * it is assumed to be a definition file containing the
 * sound file name and its gain (0.0 .. 1.0).
 * otherwise, it is taken to be the sound file name and
@ -1482,13 +1484,11 @@ static LibError list_free_all()
 }


-//-----------------------------------------------------------------------------
-
 /**
 * Send the VSrc properties to OpenAL (when we actually have a source).
 * called by snd_set * and vsrc_grant.
 *
- * @param VSrc*
+ * @param vs VSrc*
 */
 static void vsrc_latch(VSrc* vs)
 {
@ -1551,7 +1551,7 @@ static void vsrc_latch(VSrc* vs)
 /**
 * Dequeue any of the VSrc's sound buffers that are finished playing.
 *
- * @param VSrc*
+ * @param vs VSrc*
 * @return int number of entries that were removed.
 */
 static int vsrc_deque_finished_bufs(VSrc* vs)
@ -1585,7 +1585,7 @@ static double snd_update_time;
 * Update the VSrc - perform fade (if active), queue/unqueue buffers.
 * Called once a frame.
 *
- * @param VSrc*
+ * @param vs VSrc*
 * @return LibError
 */
 static LibError vsrc_update(VSrc* vs)
@ -1645,7 +1645,7 @@ static LibError vsrc_update(VSrc* vs)
 * Try to give the VSrc an AL source so that it can (re)start playing.
 * called by snd_play and voice management.
 *
- * @param VSrc*
+ * @param vs VSrc*
 * @return LibError (ERR::FAIL if no AL source is available)
 */
 static LibError vsrc_grant(VSrc* vs)
@ -1678,7 +1678,7 @@ static LibError vsrc_grant(VSrc* vs)
 * called when closing the VSrc, or when voice management decides
 * this VSrc must yield to others of higher priority.
 *
- * @param VSrc*
+ * @param vs VSrc*
 * @return LibError
 */
 static LibError vsrc_reclaim(VSrc* vs)
@ -1762,7 +1762,7 @@ LibError snd_play(Handle hvs, float static_pri)
 *
 * @param hvs Handle to VSrc
 * @param x,y,z coordinates (interpretation: see below)
- * @param relative if true, (x,y,z) is treated as relative to the listener;
+ * @param relative If true, (x,y,z) is treated as relative to the listener;
 * otherwise, it is the position in world coordinates (default).
 * @return LibError
 */
@ -1848,8 +1848,8 @@ LibError snd_set_pitch(Handle hvs, float pitch)
 * - once looping is again disabled and the sound has reached its end,
 *   the sound instance is freed automatically (as if never looped).
 *
- * @param hvs Handle to VSrc
- * @param bool loop
+ * @param hvs Handle to VSrc.
+ * @param loop Boolean to enable/disable looping on the sound source.
 * @return LibError
 */
 LibError snd_set_loop(Handle hvs, bool loop)
@ -1865,8 +1865,8 @@ LibError snd_set_loop(Handle hvs, bool loop)

 /**
 * Fade the sound source in or out over time.
- * Its gain starts at <initial_gain> immediately and is moved toward
- * <final_gain> over <length> seconds.
+ * Its gain starts at \<initial_gain\> immediately and is moved toward
+ * \<final_gain\> over \<length\> seconds.
 *
 * may be called at any time; fails with invalid handle return if
 * the sound has already been closed (e.g. it never played).
@ -1927,7 +1927,7 @@ LibError snd_fade(Handle hvs, float initial_gain, float final_gain,
 * @return bool true if playing

 **/
-bool is_playing(Handle hvs)
+bool snd_is_playing(Handle hvs)
 {
 	// (can't use H_DEREF due to bool return value)
 	VSrc* vs = H_USER_DATA(hvs, VSrc);
@ -1954,13 +1954,12 @@ static float magnitude_2(const float v[3])
 	return v[0]*v[0] + v[1]*v[1] + v[2]*v[2];
 }

-
 /**
- * determine new priority of the VSrc based on distance to listener and
+ * Determine new priority of the VSrc based on distance to listener and
 * static priority.
- * called via list_foreach.
+ * Called via list_foreach.
 *
- * @param VSrc*
+ * @param vs VSrc*
 */
 static void calc_cur_pri(VSrc* vs)
 {
--- a/source/lib/res/sound/snd_mgr.h
+++ b/source/lib/res/sound/snd_mgr.h
@ -142,14 +142,14 @@ extern const char* snd_dev_next();
 extern LibError snd_dev_set(const char* alc_new_dev_name);

 /**
- * set maximum number of voices to play simultaneously;
+ * Set maximum number of voices to play simultaneously;
 * this can be used to reduce mixing cost on low-end systems.
 *
- * @param cap maximum number of voices. ignored if higher than
- * an implementation-defined limit anyway.
+ * @param limit Maximum number of voices. Ignored if higher than
+ *		  an implementation-defined limit anyway.
 * @return LibError
 **/
-extern LibError snd_set_max_voices(size_t cap);
+extern LibError snd_set_max_voices(size_t limit);

 /**
 * set amplitude modifier, which is effectively applied to all sounds.
@ -167,64 +167,65 @@ extern LibError snd_set_master_gain(float gain);
 //

 /**
- * open and return a handle to a sound instance.
- * this loads the sound data and makes it ready for other snd_* APIs.
+ * Open and return a handle to a sound instance.
+ * This loads the sound data and makes it ready for other snd_* APIs.
 *
- * @param pathname. if a text file (extension ".txt"), it is
- *   assumed to be a definition file containing the sound file name and
- *   its gain (0.0 .. 1.0).
- * otherwise, it is taken to be the sound file name and
- *   gain is set to the default of 1.0 (no attenuation).
- *
- * @param is_stream (default false) forces the sound to be opened as a
- * stream: opening is faster, it won't be kept in memory, but
- * only one instance can be open at a time.
+ * @param vfs
+ * @param pathname If a text file (extension ".txt"), it is
+ *		  assumed to be a definition file containing the sound file name and
+ *		  its gain (0.0 .. 1.0).
+ *		  Otherwise, it is taken to be the sound file name and
+ *		  gain is set to the default of 1.0 (no attenuation).
+ * @param is_stream (Default false) Set to true to forces the sound to be opened as a
+ *		  stream: opening is faster, it won't be kept in memory, but
+ *		  only one instance can be open at a time.
 * @return Handle or LibError
 **/
-extern Handle snd_open(const PIVFS& vfs, const VfsPath& name, bool stream = false);
+extern Handle snd_open(const PIVFS& vfs, const VfsPath& pathname, bool is_stream = false);

 /**
- * close the sound instance. if it was playing, it will be stopped.
+ * Close the sound instance. If it was playing, it will be stopped.
 *
- * rationale: sounds are already closed automatically when done playing;
+ * Rationale: sounds are already closed automatically when done playing;
 * this API is provided for completeness only.
 *
- * @param hs Handle to sound instance. zeroed afterwards.
+ * @param hvs Handle to sound instance. Zeroed afterwards.
 * @return LibError
 **/
-extern LibError snd_free(Handle& hs);
+extern LibError snd_free(Handle& hvs);

 /**
- * start playing the sound.
+ * Start playing the sound.
 *
 * Notes:
- * <UL>
- *   <LI> once done playing, the sound is automatically closed (allows
- *        fire-and-forget play code).
- *   <LI> if no hardware voice is available, this sound may not be
- *        played at all, or in the case of looped sounds, start later.
- * </UL>
+ * - once done playing, the sound is automatically closed (allows
+ *   fire-and-forget play code).
+ * - if no hardware voice is available, this sound may not be
+ *   played at all, or in the case of looped sounds, start later.
 *
- * @param priority (min 0 .. max 1, default 0) indicates which sounds are
+ * @param hvs Handle to VSrc.
+ * @param static_pri (min 0 .. max 1, default 0) indicates which sounds are
 * considered more important (i.e. will override others when no hardware
 * voices are available). the static priority is attenuated by
 * distance to the listener; see snd_update.
 *
 * @return LibError
 **/
-extern LibError snd_play(Handle hs, float priority = 0.0f);
+extern LibError snd_play(Handle hvs, float static_pri = 0.0f);

 /**
- * change 3d position of the sound source.
+ * Change 3d position of the sound source.
 *
- * may be called at any time; fails with invalid handle return if
+ * May be called at any time; fails with invalid handle return if
 * the sound has already been closed (e.g. it never played).
 *
+ * @param hvs Handle to the sound. 
+ * @param x,y,z 
 * @param relative treat (x,y,z) as relative to the listener;
- * if false (the default), it is the position in world coordinates.
+ * 		  if false (the default), it is the position in world coordinates.
 * @return LibError
 **/
-extern LibError snd_set_pos(Handle hs, float x, float y, float z, bool relative = false);
+extern LibError snd_set_pos(Handle hvs, float x, float y, float z, bool relative = false);

 /**
 * change gain (amplitude modifier) of the sound source.
@ -234,7 +235,7 @@ extern LibError snd_set_pos(Handle hs, float x, float y, float z, bool relative
 * closed (e.g. it never played).
 *
 * @param gain amplitude modifier. must be non-negative;
- * 1 -> unattenuated, 0.5 -> -6 dB, 0 -> silence.
+ * 1 -\> unattenuated, 0.5 -\> -6 dB, 0 -\> silence.
 * @return LibError
 **/
 extern LibError snd_set_gain(Handle hs, float gain);
@ -252,22 +253,23 @@ extern LibError snd_set_gain(Handle hs, float gain);
 extern LibError snd_set_pitch(Handle hs, float pitch);

 /**
- * enable/disable looping on the sound source.
- * used to implement variable-length sounds (e.g. while building).
+ * Enable/disable looping on the sound source.
+ * Used to implement variable-length sounds (e.g. while building).
 *
- * may be called at any time; fails with invalid handle return if
+ * May be called at any time; fails with invalid handle return if
 * the sound has already been closed (e.g. it never played).
 *
 * Notes:
- * <UL>
- *   <LI> looping sounds are not discarded if they cannot be played for
- *        lack of a hardware voice at the moment play was requested.
- *   <LI> once looping is again disabled and the sound has reached its end,
- *        the sound instance is freed automatically (as if never looped).
- * </UL>
+ * - looping sounds are not discarded if they cannot be played for
+ * - lack of a hardware voice at the moment play was requested.
+ * - once looping is again disabled and the sound has reached its end,
+ *   the sound instance is freed automatically (as if never looped).
+ *
+ * @param hvs Handle to the sound.
+ * @param loop Boolean to enable/disable lopping on the sound.
 * @return LibError
 **/
-extern LibError snd_set_loop(Handle hs, bool loop);
+extern LibError snd_set_loop(Handle hvs, bool loop);

 /// types of fade in/out operations
 enum FadeType
@ -281,31 +283,38 @@ enum FadeType
 };

 /**
- * fade the sound source in or out over time.
+ * Fade the sound source in or out over time.
 *
- * may be called at any time; fails with invalid handle return if
+ * May be called at any time; fails with invalid handle return if
 * the sound has already been closed (e.g. it never played).
 *
- * gain starts at <initial_gain> (immediately) and is moved toward
- * <final_gain> over <length> seconds.
- * @param type of fade curve: linear, exponential or S-curve.
- * for guidance on which to use, see
+ * Gain starts at \<initial_gain\> (immediately) and is moved toward
+ * \<final_gain\> over \<length\> seconds.
+ * 
+ * @param hvs Handle to the sound.
+ * @param initial_gain
+ * @param final_gain
+ * @param length
+ * @param type Type of fade curve: linear, exponential or S-curve.
+ *
+ * For guidance on which to use, see
 * http://www.transom.org/tools/editing_mixing/200309.stupidfadetricks.html
 * you can also pass FT_ABORT to stop fading (if in progress) and
- * set gain to the current <final_gain> parameter.
- * special cases:
- * - if <initial_gain> < 0 (an otherwise illegal value), the sound's
+ * set gain to the current \<final_gain\> parameter.
+ * Special cases:
+ * - if \<initial_gain\> \< 0 (an otherwise illegal value), the sound's
 *   current gain is used as the start value (useful for fading out).
- * - if <final_gain> is 0, the sound is freed when the fade completes or
+ * - if \<final_gain\> is 0, the sound is freed when the fade completes or
 *   is aborted, thus allowing fire-and-forget fadeouts. no cases are
 *   foreseen where this is undesirable, and it is easier to implement
 *   than an extra set-free-after-fade-flag function.
 *
- * note that this function doesn't busy-wait until the fade is complete;
+ * Note that this function doesn't busy-wait until the fade is complete;
 * any number of fades may be active at a time (allows cross-fading).
- * each snd_update calculates a new gain value for all pending fades.
- * it is safe to start another fade on the same sound source while
+ * Each snd_update calculates a new gain value for all pending fades.
+ * It is safe to start another fade on the same sound source while
 * one is already in progress; the old one will be discarded.
+ *
 * @return LibError
 **/
 extern LibError snd_fade(Handle hvs, float initial_gain, float final_gain,
@ -330,14 +339,16 @@ extern LibError snd_fade(Handle hvs, float initial_gain, float final_gain,
 *
 * can later be called to reactivate sound; all settings ever changed
 * will be applied and subsequent sound load / play requests will work.
+ *
+ * @param disabled
 * @return LibError
 **/
 extern LibError snd_disable(bool disabled);

 /**
- * perform housekeeping (e.g. streaming); call once a frame.
+ * Perform housekeeping (e.g. streaming); call once a frame.
 *
- * all parameters are expressed in world coordinates. they can all be NULL
+ * All parameters are expressed in world coordinates. they can all be NULL
 * to avoid updating the listener data; this is useful when the game world
 * has not been initialized yet.
 * @param pos listener's position
@ -347,14 +358,13 @@ extern LibError snd_disable(bool disabled);
 **/
 extern LibError snd_update(const float* pos, const float* dir, const float* up);

-/** added by GF
+/**
 * find out if a sound is still playing
 *
- * @param hvs - handle to the snd to check
+ * @param hvs Handle to the snd to check.
 * @return bool true if playing
-
-**/
-extern bool is_playing(Handle hvs);
+ **/
+extern bool snd_is_playing(Handle hvs);


 /**
--- a/source/lib/sysdep/arch/x86_x64/topology.cpp
+++ b/source/lib/sysdep/arch/x86_x64/topology.cpp
@ -195,11 +195,12 @@ static size_t NumUniqueMaskedValues(const u8* apicIds, u8 mask)


 /**
- * count the number of values assumed by a certain field within APIC IDs.
+ * Count the number of values assumed by a certain field within APIC IDs.
 *
- * @param offset index of the lowest bit that is part of the field.
- * @param numValues number of values that can be assumed by the field.
- * if equal to one, the field is zero-width.
+ * @param apicIds
+ * @param offset Index of the lowest bit that is part of the field.
+ * @param numValues Number of values that can be assumed by the field.
+ *		  If equal to one, the field is zero-width.
 * @return number of unique values (for convenience of the topology code,
 * this is always at least one)
 **/
@ -314,7 +315,7 @@ class CacheRelations
 {
 public:
 	/**
-	 * add processor to the processor mask owned by cache identified by <id>
+	 * add processor to the processor mask owned by cache identified by \<id\>
 	 **/
 	void Add(u8 cacheId, size_t processor)
 	{
--- a/source/lib/sysdep/arch/x86_x64/topology.h
+++ b/source/lib/sysdep/arch/x86_x64/topology.h
@ -81,12 +81,12 @@ LIB_API size_t cpu_topology_LogicalPerCore();
 LIB_API size_t cache_topology_NumCaches();

 /**
- * @return L2 cache number (zero-based) to which <processor> belongs.
+ * @return L2 cache number (zero-based) to which \<processor\> belongs.
 **/
 LIB_API size_t cache_topology_CacheFromProcessor(size_t processor);

 /**
- * @return bit-mask of all processors sharing <cache>.
+ * @return bit-mask of all processors sharing \<cache\>.
 **/
 LIB_API uintptr_t cache_topology_ProcessorMaskFromCache(size_t cache);

--- a/source/lib/sysdep/cursor.h
+++ b/source/lib/sysdep/cursor.h
@ -30,21 +30,21 @@
 typedef void* sys_cursor;

 /**
- * create a cursor from the given color image.
+ * Create a cursor from the given color image.
 *
- * @ w, h image dimensions [pixels]. the maximum value is
- * implementation-defined; 32x32 is typical and safe.
+ * @param w,h Image dimensions [pixels]. the maximum value is
+ *		  implementation-defined; 32x32 is typical and safe.
 * @param bgra_img cursor image (BGRA format, bottom-up).
- * it is copied and can be freed after this call returns.
+ *		  It is copied and can be freed after this call returns.
 * @param hx,hy 'hotspot', i.e. offset from the upper-left corner to the
- * position where mouse clicks are registered.
- * @param cursor is 0 if the return code indicates failure, otherwise
- * a valid cursor that must be sys_cursor_free-ed when no longer needed.
+ *		  position where mouse clicks are registered.
+ * @param cursor Is 0 if the return code indicates failure, otherwise
+ *		  a valid cursor that must be sys_cursor_free-ed when no longer needed.
 **/
 extern LibError sys_cursor_create(int w, int h, void* bgra_img, int hx, int hy, sys_cursor* cursor);

 /**
- * create a transparent cursor (used to hide the system cursor)
+ * Create a transparent cursor (used to hide the system cursor).
 *
 * @param cursor is 0 if the return code indicates failure, otherwise
 * a valid cursor that must be sys_cursor_free-ed when no longer needed.
--- a/source/lib/sysdep/numa.h
+++ b/source/lib/sysdep/numa.h
@ -32,12 +32,14 @@
 LIB_API size_t numa_NumNodes();

 /**
- * @return node number (zero-based) to which <processor> belongs.
+ * @param processor
+ * @return node number (zero-based) to which \<processor\> belongs.
 **/
 LIB_API size_t numa_NodeFromProcessor(size_t processor);

 /**
- * @return bit-mask of all processors constituting <node>.
+ * @param node
+ * @return bit-mask of all processors constituting \<node\>.
 **/
 LIB_API uintptr_t numa_ProcessorMaskFromNode(size_t node);

@ -47,7 +49,8 @@ LIB_API uintptr_t numa_ProcessorMaskFromNode(size_t node);


 /**
- * @return bytes of memory available for allocation on <node>.
+ * @param node
+ * @return bytes of memory available for allocation on \<node\>.
 **/
 LIB_API size_t numa_AvailableMemory(size_t node);

--- a/source/lib/sysdep/os/win/wdbg_sym.h
+++ b/source/lib/sysdep/os/win/wdbg_sym.h
@ -44,12 +44,15 @@ struct _EXCEPTION_POINTERS;
 typedef LibError (*StackFrameCallback)(const _tagSTACKFRAME64* frame, uintptr_t cbData);

 /**
- * iterate over a call stack, invoking a callback for each frame encountered.
+ * Iterate over a call stack, invoking a callback for each frame encountered.
 *
- * @param pcontext processor context from which to start (usually taken from
- * an exception record), or 0 to walk the current stack.
+ * @param cb
+ * @param cbData
+ * @param pcontext Processor context from which to start (usually taken from
+ *		  an exception record), or 0 to walk the current stack.
+ * @param lastFuncToSkip
 *
- * note: it is safe to use debug_assert/debug_warn/CHECK_ERR even during a
+ * @note It is safe to use debug_assert/debug_warn/CHECK_ERR even during a
 * stack trace (which is triggered by debug_assert et al. in app code) because
 * nested stack traces are ignored and only the error is displayed.
 **/
--- a/source/lib/sysdep/os/win/wdll_ver.h
+++ b/source/lib/sysdep/os/win/wdll_ver.h
@ -28,14 +28,15 @@
 #define INCLUDED_WDLL_VER

 /**
- * read DLL version information and append it to a string.
+ * Read DLL version information and append it to a string.
 *
 * @param pathname of DLL (preferably the complete path, so that we don't
- * inadvertently load another one on the library search path.)
- * if no extension is given, .dll will be appended.
+ *		  inadvertently load another one on the library search path.)
+ *		  If no extension is given, .dll will be appended.
+ * @param list
 *
- * the text output includes the module name.
- * on failure, the version is given as "unknown".
+ * The text output includes the module name.
+ * On failure, the version is given as "unknown".
 **/
 extern void wdll_ver_Append(const fs::wpath& pathname, std::wstring& list);

--- a/source/lib/sysdep/os/win/whrt/counter.cpp
+++ b/source/lib/sysdep/os/win/whrt/counter.cpp
@ -43,9 +43,11 @@
 // create/destroy counters

 /**
- * @return pointer to a newly constructed ICounter subclass of type <id> at
- * the given address, or 0 iff the ID is invalid.
- * @param size maximum allowable size [bytes] of the subclass instance
+ * @param id
+ * @param address
+ * @param size Maximum allowable size [bytes] of the subclass instance
+ * @return pointer to a newly constructed ICounter subclass of type \<id\> at
+ *		   the given address, or 0 iff the ID is invalid.
 **/
 static ICounter* ConstructCounterAt(size_t id, void* address, size_t size)
 {
--- a/source/lib/sysdep/os/win/whrt/counter.h
+++ b/source/lib/sysdep/os/win/whrt/counter.h
@ -75,7 +75,7 @@ public:


 /**
- * @return a newly created ICounter of type <id> or 0 iff the ID is invalid.
+ * @return a newly created ICounter of type \<id\> or 0 iff the ID is invalid.
 * @param id integer ID (0..N-1)
 *
 * there can only be one active counter at a time; the previous one must
--- a/source/lib/sysdep/os/win/wposix/crt_posix.h
+++ b/source/lib/sysdep/os/win/wposix/crt_posix.h
@ -26,7 +26,7 @@
 * but must prevent POSIX functions (e.g. open) from being declared -
 * they would conflict with our wrapper function.
 *
- * since the headers only declare POSIX stuff #if !__STDC__, a solution
+ * since the headers only declare POSIX stuff \#if !__STDC__, a solution
 * would be to set this flag temporarily. note that MSDN says that
 * such predefined macros cannot be redefined nor may they change during
 * compilation, but this works and seems to be a fairly common practice.
--- a/source/lib/sysdep/os/win/wposix/no_crt_posix.h
+++ b/source/lib/sysdep/os/win/wposix/no_crt_posix.h
@ -24,8 +24,8 @@
 * see rationale in wposix.h.
 * prevent subsequent includes of CRT headers (e.g. <io.h>) from
 * interfering with previous declarations made by wposix headers (e.g. open).
- * this is accomplished by #defining their include guards.
- * note: #include "crt_posix.h" can undo the effects of this header and
+ * this is accomplished by \#defining their include guards.
+ * note: \#include "crt_posix.h" can undo the effects of this header and
 * pull in those headers.
 **/

--- a/source/lib/sysdep/os/win/wposix/wposix.h
+++ b/source/lib/sysdep/os/win/wposix/wposix.h
@ -39,9 +39,9 @@
 * so we want those functions (e.g. _read) to be declared correctly even
 * if switching compiler/CRT version.
 *
- * how can these conflicting requirements be reconciled? our headers #include
- * "no_crt_posix.h" to #define the CRT headers' include guards and thus
- * prevent them from declaring anything. the implementation files #include
+ * how can these conflicting requirements be reconciled? our headers \#include
+ * "no_crt_posix.h" to \#define the CRT headers' include guards and thus
+ * prevent them from declaring anything. the implementation files \#include
 * "crt_posix.h", which pulls in the CRT headers (even if "no_crt_posix.h"
 * was previously included, e.g. in the PCH). note that the CRT headers
 * would still cause conflicts with the POSIX function declarations,
--- a/source/lib/sysdep/os/win/wseh.cpp
+++ b/source/lib/sysdep/os/win/wseh.cpp
@ -95,7 +95,9 @@ static bool IsCppException(const EXCEPTION_RECORD* er)
 }

 /**
- * @param er an exception record for which IsCppException returned true.
+ * @param er An exception record for which IsCppException returned true.
+ * @param description
+ * @param maxChars
 **/
 static const wchar_t* GetCppExceptionDescription(const EXCEPTION_RECORD* er,
 	wchar_t* description, size_t maxChars)
--- a/source/lib/sysdep/sysdep.h
+++ b/source/lib/sysdep/sysdep.h
@ -89,7 +89,8 @@ extern LibError sys_error_description_r(int err, wchar_t* buf, size_t max_chars)
 /**
 * determine filename of the module to whom an address belongs.
 *
- * @param path full path to module (unchanged unless INFO::OK is returned).
+ * @param addr
+ * @param pathname Full path to module (unchanged unless INFO::OK is returned).
 * @return LibError
 *
 * note: this is useful for handling exceptions in other modules.
@ -97,9 +98,9 @@ extern LibError sys_error_description_r(int err, wchar_t* buf, size_t max_chars)
 LibError sys_get_module_filename(void* addr, fs::wpath& pathname);

 /**
- * get path to the current executable.
+ * Get path to the current executable.
 *
- * @param path full path to executable (unchanged unless INFO::OK is returned).
+ * @param pathname Full path to executable (unchanged unless INFO::OK is returned).
 * @return LibError
 *
 * this is useful for determining installation directory, e.g. for VFS.
@ -107,23 +108,23 @@ LibError sys_get_module_filename(void* addr, fs::wpath& pathname);
 LIB_API LibError sys_get_executable_name(fs::wpath& pathname);

 /**
- * get the current user's login name.
+ * Get the current user's login name.
 *
 * @return login name, or empty string on error
 */
 extern std::wstring sys_get_user_name();

 /**
- * have the user choose a directory via OS dialog.
+ * Have the user choose a directory via OS dialog.
 *
- * @param path's input value determines the starting directory for
- * faster browsing. if INFO::OK is returned, it receives
- * chosen directory path.
+ * @param path Path's input value determines the starting directory for
+ *		  faster browsing. if INFO::OK is returned, it receives
+ *		  chosen directory path.
 **/
 extern LibError sys_pick_directory(fs::wpath& path);

 /**
- * open the user's default web browser to the given URL.
+ * Open the user's default web browser to the given URL.
 **/
 extern LibError sys_open_url(const std::string& url);

--- a/source/lib/tex/tex.h
+++ b/source/lib/tex/tex.h
@ -235,28 +235,30 @@ struct Tex


 /**
- * is the texture object valid and self-consistent?
+ * Is the texture object valid and self-consistent?
+ * 
+ * @param t
 * @return LibError
 **/
 extern LibError tex_validate(const Tex* t);


 /**
- * set the orientation to which all loaded images will
+ * Set the orientation to which all loaded images will
 * automatically be converted (excepting file formats that don't specify
- * their orientation, i.e. DDS). see "Default Orientation" in docs.
- * @param orientation either TEX_BOTTOM_UP or TEX_TOP_DOWN
+ * their orientation, i.e. DDS). See "Default Orientation" in docs.
+ * @param orientation Either TEX_BOTTOM_UP or TEX_TOP_DOWN.
 **/
 extern void tex_set_global_orientation(int orientation);


 /**
- * manually register codecs. must be called before first use of a
+ * Manually register codecs. must be called before first use of a
 * codec (e.g. loading a texture).
 *
- * this would normally be taken care of by TEX_CODEC_REGISTER, but
+ * This would normally be taken care of by TEX_CODEC_REGISTER, but
 * no longer works when building as a static library.
- * workaround: hard-code a list of codecs in tex_codec.cpp and
+ * Workaround: hard-code a list of codecs in tex_codec.cpp and
 * call their registration functions.
 **/
 extern void tex_codec_register_all();
@ -272,9 +274,9 @@ extern void tex_codec_unregister_all();
 * FYI, currently BMP, TGA, JPG, JP2, PNG, DDS are supported - but don't
 * rely on this (not all codecs may be included).
 *
- * @param data input data
- * @param data_size its size [bytes]
- * @param t output texture object.
+ * @param data Input data.
+ * @param data_size Its size [bytes].
+ * @param t Output texture object.
 * @return LibError.
 **/
 extern LibError tex_decode(const shared_ptr<u8>& data, size_t data_size, Tex* t);
@ -282,10 +284,10 @@ extern LibError tex_decode(const shared_ptr<u8>& data, size_t data_size, Tex* t)
 /**
 * encode a texture into a memory buffer in the desired file format.
 *
- * @param t input texture object
- * @param extension (including '.')
- * @param da output memory array. allocated here; caller must free it
- * when no longer needed. invalid unless function succeeds.
+ * @param t Input texture object.
+ * @param extension (including '.').
+ * @param da Output memory array. Allocated here; caller must free it
+ *		  when no longer needed. Invalid unless function succeeds.
 * @return LibError
 **/
 extern LibError tex_encode(Tex* t, const std::wstring& extension, DynArray* da);
@ -299,17 +301,18 @@ extern LibError tex_encode(Tex* t, const std::wstring& extension, DynArray* da);
 *   however, we don't want to provide an alternate interface for each API;
 *   these would have to be changed whenever fields are added to Tex.
 *   instead, provide one entry point for specifying images.
- * note: since we do not know how <img> was allocated, the caller must free
+ * note: since we do not know how \<img\> was allocated, the caller must free
 *   it themselves (after calling tex_free, which is required regardless of
 *   alloc type).
 *
 * we need only add bookkeeping information and "wrap" it in
 * our Tex struct, hence the name.
 *
- * @param w, h pixel dimensions
- * @param bpp bits per pixel
- * @param flags TexFlags
- * @param img texture data. note: size is calculated from other params.
+ * @param w,h Pixel dimensions.
+ * @param bpp Bits per pixel.
+ * @param flags TexFlags.
+ * @param data Img texture data. note: size is calculated from other params.
+ * @param ofs
 * @param t output texture object.
 * @return LibError
 **/
@ -330,17 +333,19 @@ extern void tex_free(Tex* t);
 //

 /**
- * change <t>'s pixel format.
+ * Change \<t\>'s pixel format.
 *
+ * @param t Input texture object.
 * @param transforms TexFlags that are to be flipped.
 * @return LibError
 **/
 extern LibError tex_transform(Tex* t, size_t transforms);

 /**
- * change <t>'s pixel format (2nd version)
- * (note: this is equivalent to tex_transform(t, t->flags^new_flags).
+ * Change \<t\>'s pixel format (2nd version)
+ * (note: this is equivalent to tex_transform(t, t-\>flags^new_flags).
 *
+ * @param t Input texture object.
 * @param new_flags desired new value of TexFlags.
 * @return LibError
 **/
@ -400,18 +405,18 @@ typedef void (*MipmapCB)(size_t level, size_t level_w, size_t level_h, const u8*
 * for a series of mipmaps stored from base to highest, call back for
 * each level.
 *
- * @param w, h pixel dimensions
- * @param bpp bits per pixel
- * @param data series of mipmaps
- * @param levels_to_skip number of levels (counting from base) to skip, or
- * TEX_BASE_LEVEL_ONLY to only call back for the base image.
- * rationale: this avoids needing to special case for images with or
- * without mipmaps.
- * @param data_padding minimum pixel dimensions of mipmap levels.
- * this is used in S3TC images, where each level is actually stored in
- * 4x4 blocks. usually 1 to indicate levels are consecutive.
- * @param cb MipmapCB to call
- * @param cbData extra data to pass to cb
+ * @param w,h Pixel dimensions.
+ * @param bpp Bits per pixel.
+ * @param data Series of mipmaps.
+ * @param levels_to_skip Number of levels (counting from base) to skip, or
+ *		  TEX_BASE_LEVEL_ONLY to only call back for the base image.
+ *		  Rationale: this avoids needing to special case for images with or
+ *		  without mipmaps.
+ * @param data_padding Minimum pixel dimensions of mipmap levels.
+ *		  This is used in S3TC images, where each level is actually stored in
+ *		  4x4 blocks. usually 1 to indicate levels are consecutive.
+ * @param cb MipmapCB to call.
+ * @param cbData Extra data to pass to cb.
 **/
 extern void tex_util_foreach_mipmap(size_t w, size_t h, size_t bpp, const u8* data, int levels_to_skip, size_t data_padding, MipmapCB cb, void* RESTRICT cbData);

@ -421,16 +426,16 @@ extern void tex_util_foreach_mipmap(size_t w, size_t h, size_t bpp, const u8* da
 //

 /**
- * is the file's extension that of a texture format supported by tex_load?
+ * Is the file's extension that of a texture format supported by tex_load?
 *
- * rationale: tex_load complains if the given file is of an
+ * Rationale: tex_load complains if the given file is of an
 * unsupported type. this API allows users to preempt that warning
 * (by checking the filename themselves), and also provides for e.g.
 * enumerating only images in a file picker.
 * an alternative might be a flag to suppress warning about invalid files,
 * but this is open to misuse.
 *
- * @param pathname only the extension (starting with '.') is used. case-insensitive.
+ * @param pathname Only the extension (starting with '.') is used. case-insensitive.
 * @return bool
 **/
 extern bool tex_is_known_extension(const VfsPath& pathname);
@ -444,8 +449,8 @@ extern bool tex_is_known_extension(const VfsPath& pathname);
 * extra and pass the pointer as base+hdr_size. this allows writing the
 * header directly into the output buffer and makes for zero-copy IO.
 *
- * @param fn filename; only the extension (that after '.') is used.
- * case-insensitive.
+ * @param filename Filename; only the extension (that after '.') is used.
+ *		  case-insensitive.
 * @return size [bytes] or 0 on error (i.e. no codec found).
 **/
 extern size_t tex_hdr_size(const VfsPath& filename);
--- a/source/lib/tex/tex_codec.h
+++ b/source/lib/tex/tex_codec.h
@ -162,8 +162,9 @@ extern int tex_codec_register(TexCodecVTbl* c);


 /**
- * find codec that recognizes the desired output file extension.
+ * Find codec that recognizes the desired output file extension.
 *
+ * @param extension
 * @param c (out) vtbl of responsible codec
 * @return LibError; ERR::RES_UNKNOWN_FORMAT (without warning, because this is
 * called by tex_is_known_extension) if no codec indicates they can
--- a/source/lib/timer.h
+++ b/source/lib/timer.h
@ -322,7 +322,7 @@ LIB_API TimerClient* timer_AddClient(TimerClient* tc, const wchar_t* description
 * billed to it, along with a description string. These are displayed when
 * timer_DisplayClientTotals is called.
 * Invoke this at file or function scope; a (static) TimerClient pointer of
- * name <id> will be defined, which should be passed to TIMER_ACCRUE.
+ * name \<id\> will be defined, which should be passed to TIMER_ACCRUE.
 **/
 #define TIMER_ADD_CLIENT(id)\
 	static TimerClient UID__;\
--- a/source/maths/scripting/JSInterface_Vector3D.h
+++ b/source/maths/scripting/JSInterface_Vector3D.h
@ -57,8 +57,8 @@ namespace JSI_Vector3D
 		Vector3D_Info( float x, float y, float z );
 		Vector3D_Info( const CVector3D& copy );
 		Vector3D_Info( CVector3D* attach, IPropertyOwner* _owner );
-		Vector3D_Info( CVector3D* attach, IPropertyOwner* _owner, void (IPropertyOwner::*_updateFn)() );
-		Vector3D_Info( CVector3D* attach, IPropertyOwner* _owner, void (IPropertyOwner::*_updateFn)(), void (IPropertyOwner::*_freshenFn)() );
+		Vector3D_Info( CVector3D* attach, IPropertyOwner* _owner, void (IPropertyOwner::*_updateFn)(void) );
+		Vector3D_Info( CVector3D* attach, IPropertyOwner* _owner, void (IPropertyOwner::*_updateFn)(void), void (IPropertyOwner::*_freshenFn)(void) );
 		~Vector3D_Info();
 	};
 	extern JSClass JSI_class;
--- a/source/ps/FileIo.cpp
+++ b/source/ps/FileIo.cpp
@ -162,7 +162,7 @@ size_t CFileUnpacker::UnpackSize()
 }


-void CFileUnpacker::UnpackString(CStr& result)
+void CFileUnpacker::UnpackString(CStr8& result)
 {
 	const size_t length = UnpackSize();

--- a/source/ps/Game.cpp
+++ b/source/ps/Game.cpp
@ -190,8 +190,8 @@ void CGame::StartGame(const CScriptValRooted& attribs)
 * Periodic heartbeat that controls the process.
 * Simulation update is called and game status update is called.
 *
- * @param double deltaTime elapsed time since last beat in seconds.
- * @param bool doInterpolate perform interpolation if true.
+ * @param deltaTime Double. Elapsed time since last beat in seconds.
+ * @param doInterpolate Bool. Perform interpolation if true.
 * @return bool false if it can't keep up with the desired simulation rate
 *	indicating that you might want to render less frequently.
 **/
--- a/source/ps/Game.h
+++ b/source/ps/Game.h
@ -148,7 +148,7 @@ public:
 	/**
 	 * Set the simulation scale multiplier.
 	 *
-	 * @param float simRate value to set m_SimRate to.
+	 * @param simRate Float value to set m_SimRate to.
 	 *						Because m_SimRate is also used to
 	 *						scale TimeSinceLastFrame it must be
 	 *						clamped to 0.0f.
--- a/source/ps/Overlay.cpp
+++ b/source/ps/Overlay.cpp
@ -27,7 +27,7 @@ Overlay.cpp
 #include "Parser.h"


-bool CColor::ParseString(const CStr& Value, float DefaultAlpha)
+bool CColor::ParseString(const CStr8& Value, float DefaultAlpha)
 {
 	// Use the parser to parse the values
 	CParser& parser (CParserCache::Get("_[-$arg(_minus)]$value_[-$arg(_minus)]$value_[-$arg(_minus)]$value_[[-$arg(_minus)]$value_]"));
--- a/source/ps/World.cpp
+++ b/source/ps/World.cpp
@ -52,7 +52,7 @@ CLightEnv g_LightEnv;
 /**
 * Constructor.
 *
- * @param CGame * pGame pointer to the container game object.
+ * @param pGame CGame * pGame pointer to the container game object.
 **/
 CWorld::CWorld(CGame *pGame):
 	m_pGame(pGame),
--- a/source/renderer/TerrainRenderer.h
+++ b/source/renderer/TerrainRenderer.h
@ -82,8 +82,7 @@ public:
 	 * preconditions  : PrepareForRendering must have been called this
 	 * frame before calling RenderTerrain.
 	 *
-	 * @param shadow a prepared shadow map, in case rendering with shadows is enabled
-	 * @param shadowColor color of shadows
+	 * @param shadow A prepared shadow map, in case rendering with shadows is enabled.
 	 */
 	void RenderTerrain(ShadowMap* shadow);

--- a/source/renderer/TransparencyRenderer.cpp
+++ b/source/renderer/TransparencyRenderer.cpp
@ -95,7 +95,7 @@ struct PSModel
 	 *
 	 * @return Square of the estimated distance to the nearest triangle.
 	 */
-	float BackToFrontIndexSort(const CMatrix3D& objToCam);
+	float BackToFrontIndexSort(const CMatrix3D& worldToCam);

 	/// Back-link to the model
 	CModel* m_Model;
--- a/source/simulation2/components/ICmpObstructionManager.h
+++ b/source/simulation2/components/ICmpObstructionManager.h
@ -228,6 +228,7 @@ public:
 	 * Return true if the shape should be counted for collisions.
 	 * This is called for all shapes that would collide, and also for some that wouldn't.
 	 * @param tag tag of shape being tested
+	 * @param moving whether the shape is a moving unit
 	 */
 	virtual bool Allowed(ICmpObstructionManager::tag_t tag, bool moving) const = 0;
 };
--- a/source/simulation2/serialization/ISerializer.h
+++ b/source/simulation2/serialization/ISerializer.h
@ -150,27 +150,27 @@ public:
 		PutNumber(name, value);
 	}

-	void NumberI32_Unbounded(const char* name, int32_t value) ///< @copydoc NumberU8_Unbounded
+	void NumberI32_Unbounded(const char* name, int32_t value) ///@copydoc NumberU8_Unbounded()
 	{
 		PutNumber(name, value);
 	}

-	void NumberU32_Unbounded(const char* name, uint32_t value) ///< @copydoc NumberU8_Unbounded
+	void NumberU32_Unbounded(const char* name, uint32_t value) ///@copydoc NumberU8_Unbounded()
 	{
 		PutNumber(name, value);
 	}

-	void NumberFloat_Unbounded(const char* name, float value) ///< @copydoc NumberU8_Unbounded
+	void NumberFloat_Unbounded(const char* name, float value) ///@copydoc NumberU8_Unbounded()
 	{
 		PutNumber(name, value);
 	}

-	void NumberDouble_Unbounded(const char* name, double value) ///< @copydoc NumberU8_Unbounded
+	void NumberDouble_Unbounded(const char* name, double value) ///@copydoc NumberU8_Unbounded()
 	{
 		PutNumber(name, value);
 	}

-	void NumberFixed_Unbounded(const char* name, fixed value) ///< @copydoc NumberU8_Unbounded
+	void NumberFixed_Unbounded(const char* name, fixed value) ///@copydoc NumberU8_Unbounded()
 	{
 		PutNumber(name, value);
 	}
--- a/source/sound/SoundGroup.cpp
+++ b/source/sound/SoundGroup.cpp
@ -130,7 +130,7 @@ void CSoundGroup::PlayNext(const CVector3D& position)
 {
 	if(m_Intensity >= m_IntensityThreshold && !DISABLE_INTENSITY)
 	{
-		if(!is_playing(m_hReplacement))
+		if(!snd_is_playing(m_hReplacement))
 		{
 			// load up replacement file
 			const VfsPath pathname(m_filepath/m_intensity_file);
@ -203,12 +203,12 @@ void CSoundGroup::ReleaseGroup()
 {
 	for(size_t i = m_index; i<snd_group.size(); i++)
 	{
-		//if(!is_playing(snd_group[i]))	
+		//if(!snd_is_playing(snd_group[i]))
 			snd_free(snd_group[i]);
 	}
 	snd_group.clear();
 	playtimes.clear();
-	//if(is_playing(m_hReplacement))
+	//if(snd_is_playing(m_hReplacement))
 	//	snd_free(m_hReplacement);
 	m_index = 0;