From 7fa6afac37176f6039a73cc9f1ff189ebafe3c3d Mon Sep 17 00:00:00 2001 From: historic_bruno Date: Thu, 1 Mar 2012 03:55:05 +0000 Subject: [PATCH] Corrects some Doxygen comments and adds a few others of interest. This was SVN commit r11209. --- source/graphics/ColladaManager.h | 10 +-- source/gui/scripting/ScriptFunctions.cpp | 4 + source/lib/file/archive/archive.h | 2 +- source/lib/file/common/trace.h | 2 +- source/lib/res/sound/snd_mgr.cpp | 15 ++-- source/maths/BoundingBoxAligned.h | 18 ++--- source/maths/BoundingBoxOriented.h | 17 ++-- source/ps/Preprocessor.h | 30 +++---- source/ps/Profiler2.h | 3 +- source/renderer/HWLightingModelRenderer.h | 3 - source/renderer/VertexBufferManager.h | 6 +- source/scriptinterface/ScriptInterface.cpp | 16 ++++ source/scriptinterface/ScriptInterface.h | 2 + .../simulation2/components/CCmpAIManager.cpp | 11 ++- .../components/ICmpObstructionManager.h | 13 +-- source/simulation2/helpers/Geometry.h | 20 +++-- source/simulation2/helpers/Render.h | 79 +++++++++++++------ source/simulation2/helpers/Selection.h | 53 ++++++++----- 18 files changed, 190 insertions(+), 114 deletions(-) diff --git a/source/graphics/ColladaManager.h b/source/graphics/ColladaManager.h index a940492828..61678b8a3e 100644 --- a/source/graphics/ColladaManager.h +++ b/source/graphics/ColladaManager.h @@ -50,9 +50,9 @@ public: * Converts DAE to archive cached .pmd/psa and outputs the resulting path * (used by archive builder) * - * @param sourcePath[in] path of the .dae to load - * @param type[in] FileType, .pmd or .psa - * @param archiveCachePath[out] output path of the cached file + * @param[in] sourcePath path of the .dae to load + * @param[in] type FileType, .pmd or .psa + * @param[out] archiveCachePath output path of the cached file * * @return true if COLLADA converter completed successfully; or false if it failed */ @@ -63,8 +63,8 @@ private: * Creates MD5 hash key from skeletons.xml info and COLLADA converter version, * used to invalidate cached .pmd/psas * - * @param hash[out] resulting MD5 hash - * @param version[out] version passed to CCacheLoader, used if code change should force + * @param[out] hash resulting MD5 hash + * @param[out] version version passed to CCacheLoader, used if code change should force * cache invalidation */ void PrepareCacheKey(MD5& hash, u32& version); diff --git a/source/gui/scripting/ScriptFunctions.cpp b/source/gui/scripting/ScriptFunctions.cpp index bd4b30fe8e..473eca0417 100644 --- a/source/gui/scripting/ScriptFunctions.cpp +++ b/source/gui/scripting/ScriptFunctions.cpp @@ -395,6 +395,10 @@ void CameraFollow(void* UNUSED(cbdata), entity_id_t entityid) g_Game->GetView()->CameraFollow(entityid, false); } +/** + * Start / stop first-person camera following mode + * @param entityid unit id to follow. If zero, stop following mode + */ void CameraFollowFPS(void* UNUSED(cbdata), entity_id_t entityid) { if (g_Game && g_Game->GetView()) diff --git a/source/lib/file/archive/archive.h b/source/lib/file/archive/archive.h index 2209e18a13..8dca5e0eb1 100644 --- a/source/lib/file/archive/archive.h +++ b/source/lib/file/archive/archive.h @@ -91,7 +91,7 @@ struct IArchiveWriter * @param pathname the actual file to add * @param pathnameInArchive the name to store in the archive **/ - virtual Status AddFile(const OsPath& pathname, const Path& pathameInArchive) = 0; + virtual Status AddFile(const OsPath& pathname, const Path& pathnameInArchive) = 0; /** * add a file to the archive, when it is already in memory and not on disk. diff --git a/source/lib/file/common/trace.h b/source/lib/file/common/trace.h index f9f5482105..bf10fa46fc 100644 --- a/source/lib/file/common/trace.h +++ b/source/lib/file/common/trace.h @@ -110,7 +110,7 @@ struct ITrace /** * load entries from file. * - * @param osPathname (native, absolute) + * @param pathname (native, absolute) * * replaces any existing entries. **/ diff --git a/source/lib/res/sound/snd_mgr.cpp b/source/lib/res/sound/snd_mgr.cpp index 661e55d123..b324e2bc9a 100644 --- a/source/lib/res/sound/snd_mgr.cpp +++ b/source/lib/res/sound/snd_mgr.cpp @@ -139,12 +139,10 @@ static const char* alc_dev_name = 0; /** * tell OpenAL to use the specified device in future. * - * @param alc_new_dev_name Device name. + * @param alc_new_dev_name Device name; if 0, it reverts to OpenAL's default + * choice, which will also be used if this routine is never called. * @return Status * - * name = 0 reverts to OpenAL's default choice, which will also - * be used if this routine is never called. - * * the device name is typically taken from a config file at init-time; * the snd_dev * enumeration routines below are used to present a list * of choices to the user in the options screen. @@ -359,8 +357,8 @@ static int al_bufs_outstanding; * * @param data raw sound data buffer * @param size size of buffer in bytes - * @param al_fmt AL_FORMAT_ * describing the sound data - * @param al_freq sampling frequency (typically 22050 Hz) + * @param fmt AL_FORMAT_ * describing the sound data + * @param freq sampling frequency (typically 22050 Hz) * @return ALuint buffer name */ static ALuint al_buf_alloc(ALvoid* data, ALsizei size, ALenum fmt, ALsizei freq) @@ -1140,7 +1138,6 @@ static FadeRet fade(FadeInfo& fi, double cur_time, float& out_val) /** * Is the fade operation currently active? * - * @param FadeInfo * @return bool */ static bool fade_is_active(FadeInfo& fi) @@ -1319,7 +1316,7 @@ static Status VSrc_to_string(const VSrc* vs, wchar_t* buf) /** * open and return a handle to a sound instance. * - * @param pathname. if a text file (extension ".txt"), + * @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 @@ -1473,7 +1470,6 @@ static Status list_free_all() * Send the VSrc properties to OpenAL (when we actually have a source). * called by snd_set * and vsrc_grant. * - * @param VSrc* */ static void vsrc_latch(VSrc* vs) { @@ -1535,7 +1531,6 @@ static void vsrc_latch(VSrc* vs) /** * Dequeue any of the VSrc's sound buffers that are finished playing. * - * @param VSrc* * @return int number of entries that were removed. */ static int vsrc_deque_finished_bufs(VSrc* vs) diff --git a/source/maths/BoundingBoxAligned.h b/source/maths/BoundingBoxAligned.h index d79805c949..43f0a5bb76 100644 --- a/source/maths/BoundingBoxAligned.h +++ b/source/maths/BoundingBoxAligned.h @@ -43,7 +43,7 @@ public: } /** - * Transforms these bounds according to the specified transformation matrix @m, and writes the axis-aligned bounds + * Transforms these bounds according to the specified transformation matrix @p m, and writes the axis-aligned bounds * of that result to @p result. */ void Transform(const CMatrix3D& m, CBoundingBoxAligned& result) const; @@ -86,15 +86,15 @@ public: } /** - * Returns true if the ray originating in @p origin and with unit direction vector @p dir intersects this AABB, false otherwise. - * Additionally, returns the distance in the positive direction from the origin of the ray to the entry and exit points in - * the bounding box in @p tmin and @p tmax. If the origin is inside the box, then this is counted as an intersection and one - * of @p tMin and @p tMax may be negative. - * + * Check if a given ray intersects this AABB. * See also Real-Time Rendering, Third Edition by T. Akenine-Moller, p. 741--742. - * - * @param origin Origin of the ray. - * @param dir Direction vector of the ray, defining the positive direction of the ray. Must be of unit length. + * + * @param[in] origin Origin of the ray. + * @param[in] dir Direction vector of the ray, defining the positive direction of the ray. Must be of unit length. + * @param[out] tmin,tmax distance in the positive direction from the origin of the ray to the entry and exit points in + * the bounding box. If the origin is inside the box, then this is counted as an intersection and one of @p tMin and @p tMax may be negative. + * + * @return true if the ray originating in @p origin and with unit direction vector @p dir intersects this AABB, false otherwise. */ bool RayIntersect(const CVector3D& origin, const CVector3D& dir, float& tmin, float& tmax) const; diff --git a/source/maths/BoundingBoxOriented.h b/source/maths/BoundingBoxOriented.h index fd796ef037..7d05d542d9 100644 --- a/source/maths/BoundingBoxOriented.h +++ b/source/maths/BoundingBoxOriented.h @@ -51,17 +51,16 @@ public: explicit CBoundingBoxOriented(const CBoundingBoxAligned& bound); /** - * Returns true if the ray originating in @p origin and with unit direction vector @p dir intersects this box, false otherwise. - * Additionally, returns the distance in the positive direction from the origin of the ray to the entry and exit points in the - * box in @p tMin and @p tMax. If the origin is inside the box, then this is counted as an intersection and one of @p tMin and - * @p tMax may be negative. - * - * Should not be used if IsEmpty() is true. + * Check if a given ray intersects this box. * See also Real-Time Rendering, Third Edition by T. Akenine-Möller, p. 741--742. - * + * Should not be used if IsEmpty() is true. * - * @param origin Origin of the ray. - * @param dir Direction vector of the ray, defining the positive direction of the ray. Must be of unit length. + * @param[in] origin Origin of the ray. + * @param[in] dir Direction vector of the ray, defining the positive direction of the ray. Must be of unit length. + * @param[out] tMin,tMax distance in the positive direction from the origin of the ray to the entry and exit points in the + * box. If the origin is inside the box, then this is counted as an intersection and one of @p tMin and @p tMax may be negative. + * + * @return true if the ray originating in @p origin and with unit direction vector @p dir intersects this box, false otherwise. */ bool RayIntersect(const CVector3D& origin, const CVector3D& dir, float& tMin, float& tMax) const; diff --git a/source/ps/Preprocessor.h b/source/ps/Preprocessor.h index 5d56e351d1..3f3321ac90 100644 --- a/source/ps/Preprocessor.h +++ b/source/ps/Preprocessor.h @@ -46,18 +46,18 @@ THE SOFTWARE. * * Here's a list of supported features: *