From 1706363bab433221a793a6f315a3ba7eb0235cd9 Mon Sep 17 00:00:00 2001 From: Ykkrosh Date: Thu, 29 Jul 2010 15:55:41 +0000 Subject: [PATCH] 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. --- docs/doxygen/config | 12 +- source/collada/CommonConvert.h | 4 +- source/collada/StdSkeletons.h | 6 +- source/graphics/ColladaManager.h | 3 +- source/graphics/UnitManager.cpp | 2 +- source/gui/CGUI.h | 9 +- source/gui/CGUISprite.h | 2 +- source/gui/CList.h | 2 +- source/gui/GUIbase.h | 5 +- source/gui/GUItext.h | 9 +- source/gui/GUIutil.h | 5 +- source/gui/IGUIObject.h | 25 +--- source/gui/IGUIScrollBar.h | 28 ++-- source/gui/IGUITextOwner.h | 1 + source/gui/scripting/JSInterface_GUITypes.cpp | 1 - source/lib/allocators/allocators.h | 18 +-- source/lib/allocators/bucket.h | 10 +- source/lib/allocators/dynarray.h | 6 +- source/lib/allocators/pool.h | 15 +- source/lib/base32.h | 6 +- source/lib/bits.h | 12 +- source/lib/byte_order.h | 8 +- source/lib/code_annotation.h | 18 +-- source/lib/debug.h | 40 ++--- source/lib/debug_stl.h | 10 +- source/lib/file/archive/archive_zip.cpp | 4 +- source/lib/file/archive/codec.h | 18 ++- source/lib/file/common/trace.h | 2 +- source/lib/file/file_system_util.h | 24 +-- source/lib/file/io/block_cache.h | 7 +- source/lib/file/vfs/file_cache.h | 8 +- source/lib/file/vfs/vfs.h | 29 ++-- source/lib/file/vfs/vfs_lookup.h | 8 +- source/lib/path_util.h | 8 +- source/lib/res/graphics/cursor.h | 17 ++- source/lib/res/graphics/ogl_shader.h | 6 +- source/lib/res/graphics/ogl_tex.h | 34 +++-- source/lib/res/graphics/unifont.h | 12 +- source/lib/res/sound/snd_mgr.cpp | 49 +++---- source/lib/res/sound/snd_mgr.h | 138 ++++++++++-------- source/lib/sysdep/arch/x86_x64/topology.cpp | 11 +- source/lib/sysdep/arch/x86_x64/topology.h | 4 +- source/lib/sysdep/cursor.h | 16 +- source/lib/sysdep/numa.h | 9 +- source/lib/sysdep/os/win/wdbg_sym.h | 11 +- source/lib/sysdep/os/win/wdll_ver.h | 11 +- source/lib/sysdep/os/win/whrt/counter.cpp | 8 +- source/lib/sysdep/os/win/whrt/counter.h | 2 +- source/lib/sysdep/os/win/wposix/crt_posix.h | 2 +- .../lib/sysdep/os/win/wposix/no_crt_posix.h | 4 +- source/lib/sysdep/os/win/wposix/wposix.h | 6 +- source/lib/sysdep/os/win/wseh.cpp | 4 +- source/lib/sysdep/sysdep.h | 19 +-- source/lib/tex/tex.h | 83 ++++++----- source/lib/tex/tex_codec.h | 3 +- source/lib/timer.h | 2 +- source/maths/scripting/JSInterface_Vector3D.h | 4 +- source/ps/FileIo.cpp | 2 +- source/ps/Game.cpp | 4 +- source/ps/Game.h | 2 +- source/ps/Overlay.cpp | 2 +- source/ps/World.cpp | 2 +- source/renderer/TerrainRenderer.h | 3 +- source/renderer/TransparencyRenderer.cpp | 2 +- .../components/ICmpObstructionManager.h | 1 + .../simulation2/serialization/ISerializer.h | 10 +- source/sound/SoundGroup.cpp | 6 +- 67 files changed, 449 insertions(+), 405 deletions(-) diff --git a/docs/doxygen/config b/docs/doxygen/config index f7b493e266..b50be4a736 100644 --- 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 diff --git a/source/collada/CommonConvert.h b/source/collada/CommonConvert.h index c858f93574..37c625d938 100644 --- 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 nodes at the document level (i.e. directly in ). + * access to \ nodes at the document level (i.e. directly in \). */ class FColladaDocument { @@ -81,7 +81,7 @@ public: /** Returns the FCDocument that was loaded. */ FCDocument* GetDocument() const { return document.get(); } - /** Returns the data from the element. */ + /** Returns the \ data from the \ element. */ FCDExtra* GetExtra() const { return extra.get(); } private: diff --git a/source/collada/StdSkeletons.h b/source/collada/StdSkeletons.h index 07f3152522..c8bbad339a 100644 --- 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); diff --git a/source/graphics/ColladaManager.h b/source/graphics/ColladaManager.h index e82f2a7b8e..187e53e064 100644 --- 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. diff --git a/source/graphics/UnitManager.cpp b/source/graphics/UnitManager.cpp index 52023b4360..c3143aec23 100644 --- 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& selections) +CUnit* CUnitManager::CreateUnit(const CStrW& actorName, const std::set& selections) { if (! m_ObjectManager) return NULL; diff --git a/source/gui/CGUI.h b/source/gui/CGUI.h index 7033a93177..f09f7475da 100644 --- 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() */ diff --git a/source/gui/CGUISprite.h b/source/gui/CGUISprite.h index ab29ed6251..ea8ed0aa9c 100644 --- 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 in the GUI + * like a collage. View the section \ in the GUI * TDD for more information. * * Drawing routine is located in CGUI diff --git a/source/gui/CList.h b/source/gui/CList.h index a71faaa2cb..797fe63f0e 100644 --- a/source/gui/CList.h +++ b/source/gui/CList.h @@ -111,7 +111,7 @@ protected: virtual void SelectLastElement(); /** - * Handle the tag. + * Handle the \ tag. */ virtual bool HandleAdditionalChildren(const XMBElement& child, CXeromyces* pFile); diff --git a/source/gui/GUIbase.h b/source/gui/GUIbase.h index 47b5d71513..65af921251 100644 --- 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 diff --git a/source/gui/GUItext.h b/source/gui/GUItext.h index bea9db92fe..bb1a2116aa 100644 --- 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, diff --git a/source/gui/GUIutil.h b/source/gui/GUIutil.h index ac1b2ca5c5..a8386811c8 100644 --- 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, diff --git a/source/gui/IGUIObject.h b/source/gui/IGUIObject.h index f707a38322..02a23ffbde 100644 --- 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 diff --git a/source/gui/IGUIScrollBar.h b/source/gui/IGUIScrollBar.h index 2d426a23b6..5985ecadd1 100644 --- 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 diff --git a/source/gui/IGUITextOwner.h b/source/gui/IGUITextOwner.h index 11da3de702..a10e7f866f 100644 --- 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 diff --git a/source/gui/scripting/JSInterface_GUITypes.cpp b/source/gui/scripting/JSInterface_GUITypes.cpp index 4c9a694212..0d09e6937a 100644 --- 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, diff --git a/source/lib/allocators/allocators.h b/source/lib/allocators/allocators.h index a91dda3b05..2687036782 100644 --- 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 bytes of zeroed memory. + * Allocate \ 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 bytes + * @param storage Caller-allocated memory of at least \ bytes * (typically a static array of bytes) - * @param in_use_flag Pointer to a flag we set when is in-use. + * @param in_use_flag Pointer to a flag we set when \ is in-use. * @param size [bytes] to allocate - * @return allocated memory (typically = , but falls back to + * @return allocated memory (typically = \, 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 bytes of storage and prepare for use with +// define \ bytes of storage and prepare \ 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_wrapper; +OverrunProtector\ 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- diff --git a/source/lib/allocators/bucket.h b/source/lib/allocators/bucket.h index eeba38c9c3..b13dc995df 100644 --- 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 . + * free all memory that ensued from \. * * 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); diff --git a/source/lib/allocators/dynarray.h b/source/lib/allocators/dynarray.h index 671ab527b6..77d86c39b7 100644 --- 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 bytes starting at da->pos are committed and + * Make sure at least \ 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 **/ diff --git a/source/lib/allocators/pool.h b/source/lib/allocators/pool.h index bb8fcb6fac..b57d957ec2 100644 --- a/source/lib/allocators/pool.h +++ b/source/lib/allocators/pool.h @@ -56,7 +56,7 @@ struct Pool }; /** - * pass as pool_create's param to indicate variable-sized allocs + * pass as pool_create's \ 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); diff --git a/source/lib/base32.h b/source/lib/base32.h index 97603012f7..fbeaccc97c 100644 --- 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); diff --git a/source/lib/bits.h b/source/lib/bits.h index e396c83272..a9b2e6d4af 100644 --- a/source/lib/bits.h +++ b/source/lib/bits.h @@ -28,7 +28,7 @@ #define INCLUDED_BITS /** - * value of bit number . + * value of bit number \. * * @param n bit index. * @@ -44,13 +44,12 @@ T Bit(size_t n) } /** - * pretty much the same as Bit. + * pretty much the same as Bit\. * this is intended for the initialization of enum values, where a * compile-time constant is required. **/ #define BIT(n) (1u << (n)) - template 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 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 T round_up(T n, T multiple) diff --git a/source/lib/byte_order.h b/source/lib/byte_order.h index d7296103e4..cec2d9c3c0 100644 --- 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 (truncated to 8) bytes of little-endian data to u64, - * starting at address

(need not be aligned). + * zero-extend \ (truncated to 8) bytes of little-endian data to u64, + * starting at address \ (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 (truncated to 8) bytes of little-endian data to i64, - * starting at address

(need not be aligned). + * sign-extend \ (truncated to 8) bytes of little-endian data to i64, + * starting at address \ (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); diff --git a/source/lib/code_annotation.h b/source/lib/code_annotation.h index 842a877673..a63acb6f0f 100644 --- 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 struct static_assert_; @@ -140,16 +140,10 @@ template<> struct static_assert_ }; /** - * 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)] diff --git a/source/lib/debug.h b/source/lib/debug.h index c0b863fc30..57a4c4dcd3 100644 --- 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 identifies output type). + * the alphanumeric-only \ 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 evaluates to non-zero. used to validate + * make sure the expression \ 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 (possibly indirectly via other + * user source has included \ (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); diff --git a/source/lib/debug_stl.h b/source/lib/debug_stl.h index 3345bceadb..b58f871837 100644 --- 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, - * std::allocator >" => "string". + * example: "std::basic_string\, + * std::allocator\ \>" => "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); diff --git a/source/lib/file/archive/archive_zip.cpp b/source/lib/file/archive/archive_zip.cpp index d90a1bf53f..d0515702d2 100644 --- 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) diff --git a/source/lib/file/archive/codec.h b/source/lib/file/archive/codec.h index 206cafbc0b..813a281b38 100644 --- 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. **/ diff --git a/source/lib/file/common/trace.h b/source/lib/file/common/trace.h index 5a28d40d30..73e4c770ba 100644 --- 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. **/ diff --git a/source/lib/file/file_system_util.h b/source/lib/file/file_system_util.h index d9a7be834f..58bc73a762 100644 --- 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); diff --git a/source/lib/file/io/block_cache.h b/source/lib/file/io/block_cache.h index 0107a7c39b..623d19ca65 100644 --- 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& buf); diff --git a/source/lib/file/vfs/file_cache.h b/source/lib/file/vfs/file_cache.h index 5cb06b6205..6ca1178495 100644 --- 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& data, size_t size, size_t cost = 1); diff --git a/source/lib/file/vfs/vfs.h b/source/lib/file/vfs/vfs.h index 69af27c152..85f0a030b8 100644 --- 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& 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. **/ diff --git a/source/lib/file/vfs/vfs_lookup.h b/source/lib/file/vfs/vfs_lookup.h index ffe9fdf292..1339d072b3 100644 --- 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. diff --git a/source/lib/path_util.h b/source/lib/path_util.h index d6659c5c8e..a834a2b48a 100644 --- 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 . + * @param path Input path. + * @return pointer to name component within \. **/ LIB_API const wchar_t* path_name_only(const wchar_t* path); diff --git a/source/lib/res/graphics/cursor.h b/source/lib/res/graphics/cursor.h index a11a9914f8..5ed1b0b60c 100644 --- 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); diff --git a/source/lib/res/graphics/ogl_shader.h b/source/lib/res/graphics/ogl_shader.h index 27ff7e6262..69539acee3 100644 --- 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. diff --git a/source/lib/res/graphics/ogl_tex.h b/source/lib/res/graphics/ogl_tex.h index 243cc84bdd..154d2d5382 100644 --- 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: -*

    -*
  • enables texturing on TMU 0 and binds the texture to it; -*
  • frees the texel data! see ogl_tex_get_data. -*
+* - 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 changed +* @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. */ diff --git a/source/lib/res/graphics/unifont.h b/source/lib/res/graphics/unifont.h index 619e04dc31..2172a95164 100644 --- 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. * diff --git a/source/lib/res/sound/snd_mgr.cpp b/source/lib/res/sound/snd_mgr.cpp index a65e1c8071..65a0102a47 100644 --- 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 immediately and is moved toward - * over seconds. + * Its gain starts at \ immediately and is moved toward + * \ over \ 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) { diff --git a/source/lib/res/sound/snd_mgr.h b/source/lib/res/sound/snd_mgr.h index 7a00f36487..2d18a2e9d1 100644 --- 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: - *
    - *
  • 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. - *
+ * - 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: - *
    - *
  • 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). - *
+ * - 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 (immediately) and is moved toward - * over seconds. - * @param type of fade curve: linear, exponential or S-curve. - * for guidance on which to use, see + * Gain starts at \ (immediately) and is moved toward + * \ over \ 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 parameter. - * special cases: - * - if < 0 (an otherwise illegal value), the sound's + * set gain to the current \ parameter. + * Special cases: + * - if \ \< 0 (an otherwise illegal value), the sound's * current gain is used as the start value (useful for fading out). - * - if is 0, the sound is freed when the fade completes or + * - if \ 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); /** diff --git a/source/lib/sysdep/arch/x86_x64/topology.cpp b/source/lib/sysdep/arch/x86_x64/topology.cpp index 8135e802ed..af24f6b51b 100644 --- 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 + * add processor to the processor mask owned by cache identified by \ **/ void Add(u8 cacheId, size_t processor) { diff --git a/source/lib/sysdep/arch/x86_x64/topology.h b/source/lib/sysdep/arch/x86_x64/topology.h index 4e231b64d4..5f0ae7969a 100644 --- 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 belongs. + * @return L2 cache number (zero-based) to which \ belongs. **/ LIB_API size_t cache_topology_CacheFromProcessor(size_t processor); /** - * @return bit-mask of all processors sharing . + * @return bit-mask of all processors sharing \. **/ LIB_API uintptr_t cache_topology_ProcessorMaskFromCache(size_t cache); diff --git a/source/lib/sysdep/cursor.h b/source/lib/sysdep/cursor.h index 3ebdfb042e..cd4b328158 100644 --- 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. diff --git a/source/lib/sysdep/numa.h b/source/lib/sysdep/numa.h index 3aa76430b4..a47aa2e64d 100644 --- 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 belongs. + * @param processor + * @return node number (zero-based) to which \ belongs. **/ LIB_API size_t numa_NodeFromProcessor(size_t processor); /** - * @return bit-mask of all processors constituting . + * @param node + * @return bit-mask of all processors constituting \. **/ 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 . + * @param node + * @return bytes of memory available for allocation on \. **/ LIB_API size_t numa_AvailableMemory(size_t node); diff --git a/source/lib/sysdep/os/win/wdbg_sym.h b/source/lib/sysdep/os/win/wdbg_sym.h index 870edf959c..7e12384bb1 100644 --- 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. **/ diff --git a/source/lib/sysdep/os/win/wdll_ver.h b/source/lib/sysdep/os/win/wdll_ver.h index 90cef7e169..d4dcffc310 100644 --- 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); diff --git a/source/lib/sysdep/os/win/whrt/counter.cpp b/source/lib/sysdep/os/win/whrt/counter.cpp index efd1a9426d..f948625fe3 100644 --- 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 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 \ at + * the given address, or 0 iff the ID is invalid. **/ static ICounter* ConstructCounterAt(size_t id, void* address, size_t size) { diff --git a/source/lib/sysdep/os/win/whrt/counter.h b/source/lib/sysdep/os/win/whrt/counter.h index 03b2114e9a..5fa04e8b70 100644 --- 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 or 0 iff the ID is invalid. + * @return a newly created ICounter of type \ 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 diff --git a/source/lib/sysdep/os/win/wposix/crt_posix.h b/source/lib/sysdep/os/win/wposix/crt_posix.h index 79eff506b8..7c16b5ba33 100644 --- 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. diff --git a/source/lib/sysdep/os/win/wposix/no_crt_posix.h b/source/lib/sysdep/os/win/wposix/no_crt_posix.h index 3e01e14c55..4dc54aeec7 100644 --- 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. ) 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. **/ diff --git a/source/lib/sysdep/os/win/wposix/wposix.h b/source/lib/sysdep/os/win/wposix/wposix.h index aee067e5bc..e065875560 100644 --- 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, diff --git a/source/lib/sysdep/os/win/wseh.cpp b/source/lib/sysdep/os/win/wseh.cpp index 2f6bdc399c..da4e151925 100644 --- 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) diff --git a/source/lib/sysdep/sysdep.h b/source/lib/sysdep/sysdep.h index 8df0e181e5..e59ab4743d 100644 --- 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); diff --git a/source/lib/tex/tex.h b/source/lib/tex/tex.h index 55ab4fbfe4..6790ab8190 100644 --- 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& data, size_t data_size, Tex* t); @@ -282,10 +284,10 @@ extern LibError tex_decode(const shared_ptr& 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 was allocated, the caller must free + * note: since we do not know how \ 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 's pixel format. + * Change \'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 's pixel format (2nd version) - * (note: this is equivalent to tex_transform(t, t->flags^new_flags). + * Change \'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); diff --git a/source/lib/tex/tex_codec.h b/source/lib/tex/tex_codec.h index d35e0bad0c..5d6ef5f885 100644 --- 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 diff --git a/source/lib/timer.h b/source/lib/timer.h index a56c6f8883..e5f4fbfe77 100644 --- 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 will be defined, which should be passed to TIMER_ACCRUE. + * name \ will be defined, which should be passed to TIMER_ACCRUE. **/ #define TIMER_ADD_CLIENT(id)\ static TimerClient UID__;\ diff --git a/source/maths/scripting/JSInterface_Vector3D.h b/source/maths/scripting/JSInterface_Vector3D.h index aa445f2ef6..f2486bacae 100644 --- 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; diff --git a/source/ps/FileIo.cpp b/source/ps/FileIo.cpp index 16bf51556e..a8dcf4fd0e 100644 --- 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(); diff --git a/source/ps/Game.cpp b/source/ps/Game.cpp index e7ae4c8d95..65f7dad6db 100644 --- 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. **/ diff --git a/source/ps/Game.h b/source/ps/Game.h index ec8ee60816..1f7d01a7bb 100644 --- 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. diff --git a/source/ps/Overlay.cpp b/source/ps/Overlay.cpp index e3b830d748..99c7f6c716 100644 --- 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_]")); diff --git a/source/ps/World.cpp b/source/ps/World.cpp index 266a9ba8f3..fa5c6d8d4a 100644 --- 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), diff --git a/source/renderer/TerrainRenderer.h b/source/renderer/TerrainRenderer.h index af8b5842b9..676eac05cb 100644 --- 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); diff --git a/source/renderer/TransparencyRenderer.cpp b/source/renderer/TransparencyRenderer.cpp index 562fcaf8a7..4e09f97c07 100644 --- 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; diff --git a/source/simulation2/components/ICmpObstructionManager.h b/source/simulation2/components/ICmpObstructionManager.h index 7b53b39217..6bea091313 100644 --- 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; }; diff --git a/source/simulation2/serialization/ISerializer.h b/source/simulation2/serialization/ISerializer.h index d37ade45e4..348020d720 100644 --- 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); } diff --git a/source/sound/SoundGroup.cpp b/source/sound/SoundGroup.cpp index 77a19cac08..a07ee1d023 100644 --- 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