Corrects some Doxygen comments and adds a few others of interest.

This was SVN commit r11209.

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[in] sourcePath path of the .dae to load
-	 * @param type[in] FileType, .pmd or .psa
+	 * @param[in] type FileType, .pmd or .psa
-	 * @param archiveCachePath[out] output path of the cached file
+	 * @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[out] hash resulting MD5 hash
-	 * @param version[out] version passed to CCacheLoader, used if code change should force
+	 * @param[out] version version passed to CCacheLoader, used if code change should force
 	 *		  cache invalidation
 	 */
 	void PrepareCacheKey(MD5& hash, u32& version);

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())

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.

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.
 	 **/

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 fmt AL_FORMAT_ * describing the sound data
- * @param al_freq sampling frequency (typically 22050 Hz)
+ * @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)

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.
+	 * Check if a given ray intersects this AABB.
-	 * 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. 
-	 * 
 	 * See also Real-Time Rendering, Third Edition by T. Akenine-Moller, p. 741--742.
-	 * 
+	 *
-	 * @param origin Origin of the ray.
+	 * @param[in] 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] 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;
 

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.
+	 * Check if a given ray intersects this box.
-	 * 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.
 	 * 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[in] 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] 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;
 

source/ps/Preprocessor.h

@@ -46,18 +46,18 @@ THE SOFTWARE.
  *
  * Here's a list of supported features:
  * <ul>
- * <li>Fast memory allocation-less operation (mostly).
+ * <li>Fast memory allocation-less operation (mostly).</li>
- * <li>Line continuation (backslash-newline) is swallowed.
+ * <li>Line continuation (backslash-newline) is swallowed.</li>
  * <li>Line numeration is fully preserved by inserting empty lines where
  *     required. This is crucial if, say, GLSL compiler reports you an error
- *     with a line number.
+ *     with a line number.</li>
- * <li>#define: Parametrized and non-parametrized macros. Invoking a macro with
+ * <li>\#define: Parametrized and non-parametrized macros. Invoking a macro with
- *     less arguments than it takes assignes empty values to missing arguments.
+ *     less arguments than it takes assignes empty values to missing arguments.</li>
- * <li>#undef: Forget defined macros
+ * <li>\#undef: Forget defined macros</li>
- * <li>#ifdef/#ifndef/#else/#endif: Conditional suppression of parts of code.
+ * <li>\#ifdef/\#ifndef/\#else/\#endif: Conditional suppression of parts of code.</li>
- * <li>#if: Supports numeric expression of any complexity, also supports the
+ * <li>\#if: Supports numeric expression of any complexity, also supports the
- *     defined() pseudo-function.
+ *     defined() pseudo-function.</li>
- * <ul>
+ * </ul>
  */
 class CPreprocessor
 {
@@ -243,7 +243,7 @@ class CPreprocessor
     Token HandleDirective (Token &iToken, int iLine);
 
     /**
-     * Handle a #define directive.
+     * Handle a \#define directive.
      * @param iBody
      *     The body of the directive (everything after the directive
      *     until end of line).
@@ -267,7 +267,7 @@ class CPreprocessor
     bool HandleUnDef (Token &iBody, int iLine);
 
     /**
-     * Handle an #ifdef directive.
+     * Handle an \#ifdef directive.
      * @param iBody
      *     The body of the directive (everything after the directive
      *     until end of line).
@@ -279,7 +279,7 @@ class CPreprocessor
     bool HandleIfDef (Token &iBody, int iLine);
 
     /**
-     * Handle an #if directive.
+     * Handle an \#if directive.
      * @param iBody
      *     The body of the directive (everything after the directive
      *     until end of line).
@@ -291,7 +291,7 @@ class CPreprocessor
     bool HandleIf (Token &iBody, int iLine);
 
     /**
-     * Handle an #else directive.
+     * Handle an \#else directive.
      * @param iBody
      *     The body of the directive (everything after the directive
      *     until end of line).
@@ -303,7 +303,7 @@ class CPreprocessor
     bool HandleElse (Token &iBody, int iLine);
 
     /**
-     * Handle an #endif directive.
+     * Handle an \#endif directive.
      * @param iBody
      *     The body of the directive (everything after the directive
      *     until end of line).

source/ps/Profiler2.h

@@ -21,7 +21,8 @@
  */
 
 /**
- * @file New profiler (complementing the older CProfileManager)
+ * @file
+ * New profiler (complementing the older CProfileManager)
  * 
  * The profiler is designed for analysing framerate fluctuations or glitches,
  * and temporal relationships between threads.

source/renderer/HWLightingModelRenderer.h

@@ -37,9 +37,6 @@ class ShaderModelRenderer : public ModelVertexRenderer
 public:
 	/**
 	 * HWLightingModelRenderer: Constructor.
-	 *
-	 * @param colorIsDiffuseOnly if true, the primary color sent to the fragment stage
-	 * contains only the diffuse term, and not the ambient
 	 */
 	ShaderModelRenderer();
 	~ShaderModelRenderer();

source/renderer/VertexBufferManager.h

@@ -34,8 +34,10 @@ public:
 	void Shutdown();
 	
 	/**
-	 * Try to allocate a buffer of given number of vertices (each of given size),
+	 * Try to allocate a vertex buffer of the given size and type.
-	 * and with the given type.
+	 *
+	 * @param vertexSize size of each vertex in the buffer
+	 * @param numVertices number of vertices in the buffer
 	 * @param usage typically GL_STATIC_DRAW or GL_DYNAMIC_DRAW
 	 * @param target typically GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_BUFFER
 	 * @return chunk, or NULL if no free chunks available

source/scriptinterface/ScriptInterface.cpp

@@ -47,8 +47,24 @@
 
 #include "scriptinterface/ScriptExtraHeaders.h"
 
+/**
+ * @file
+ * Abstractions of various SpiderMonkey features.
+ * Engine code should be using functions of these interfaces rather than
+ * directly accessing the underlying JS api.
+ */
+
 ////////////////////////////////////////////////////////////////
 
+/**
+ * Abstraction around a SpiderMonkey JSRuntime.
+ * Each ScriptRuntime can be used to initialize several ScriptInterface
+ * contexts which can then share data, but a single ScriptRuntime should
+ * only be used on a single thread.
+ *
+ * (One means to share data between threads and runtimes is to create
+ * a ScriptInterface::StructuredClone.)
+ */
 class ScriptRuntime
 {
 public:

source/scriptinterface/ScriptInterface.h

@@ -79,6 +79,8 @@ public:
 	 * Constructor.
 	 * @param nativeScopeName Name of global object that functions (via RegisterFunction) will
 	 *   be placed into, as a scoping mechanism; typically "Engine"
+	 * @param debugName Name of this interface for CScriptStats purposes.
+	 * @param runtime ScriptRuntime to use when initializing this interface.
 	 */
 	ScriptInterface(const char* nativeScopeName, const char* debugName, const shared_ptr<ScriptRuntime>& runtime);
 

source/simulation2/components/CCmpAIManager.cpp

@@ -42,8 +42,8 @@
 #include "simulation2/serialization/SerializeTemplates.h"
 
 /**
- * @file Player AI interface.
+ * @file
- *
+ * Player AI interface.
  * AI is primarily scripted, and the CCmpAIManager component defined here
  * takes care of managing all the scripts.
  *
@@ -66,6 +66,9 @@
  * is designed to hopefully support threading when we want it.
  */
 
+/**
+ * Implements worker thread for CCmpAIManager.
+ */
 class CAIWorker
 {
 private:
@@ -515,7 +518,9 @@ private:
 };
 
 
-
+/**
+ * Implementation of ICmpAIManager.
+ */
 class CCmpAIManager : public ICmpAIManager
 {
 public:

source/simulation2/components/ICmpObstructionManager.h

@@ -94,25 +94,26 @@ public:
 	/**
 	 * Register a static shape.
 	 * @param ent entity ID associated with this shape (or INVALID_ENTITY if none)
-	 * @param x X coordinate of center, in world space
+	 * @param x,z coordinates of center, in world space
-	 * @param z Z coordinate of center, in world space
 	 * @param a angle of rotation (clockwise from +Z direction)
 	 * @param w width (size along X axis)
 	 * @param h height (size along Z axis)
 	 * @param flags a set of EFlags values
 	 * @return a valid tag for manipulating the shape
+	 * @see StaticShape
 	 */
 	virtual tag_t AddStaticShape(entity_id_t ent, entity_pos_t x, entity_pos_t z, entity_angle_t a, entity_pos_t w, entity_pos_t h, flags_t flags) = 0;
 
 	/**
 	 * Register a unit shape.
 	 * @param ent entity ID associated with this shape (or INVALID_ENTITY if none)
-	 * @param x X coordinate of center, in world space
+	 * @param x,z coordinates of center, in world space
-	 * @param z Z coordinate of center, in world space
+	 * @param r radius of circle or half the unit's width/height
-	 * @param r radius (half the unit's width/height)
 	 * @param flags a set of EFlags values
-	 * @param moving whether the unit is currently moving through the world or is stationary
+	 * @param group control group (typically the owner entity, or a formation controller entity
+	 *	- units ignore collisions with others in the same group)
 	 * @return a valid tag for manipulating the shape
+	 * @see UnitShape
 	 */
 	virtual tag_t AddUnitShape(entity_id_t ent, entity_pos_t x, entity_pos_t z, entity_angle_t r, flags_t flags, entity_id_t group) = 0;
 

source/simulation2/helpers/Geometry.h

@@ -31,10 +31,9 @@ namespace Geometry
 {
 
 /**
- * Returns true if @p point is inside the square with rotated X axis unit vector @p u and rotated Z axis unit vector @p v,
+ * Checks if a point is inside the given rotated square or rectangle.
- * and half dimensions specified by @p halfSizes. Currently assumes the @p u and @p v vectors are perpendicular. Can also
- * be used for rectangles.
  *
+ * @note Currently assumes the @p u and @p v vectors are perpendicular.
  * @param point point vector of the point that is to be tested relative to the origin (center) of the shape.
  * @param u rotated X axis unit vector relative to the absolute XZ plane. Indicates the orientation of the rectangle. If not rotated,
  *          this value is the absolute X axis unit vector (1,0). If rotated by angle theta, this should be (cos theta, -sin theta), as
@@ -42,7 +41,10 @@ namespace Geometry
  * @param v rotated Z axis unit vector relative to the absolute XZ plane. Indicates the orientation of the rectangle. If not rotated,
  *          this value is the absolute Z axis unit vector (0,1). If rotated by angle theta, this should be (sin theta, cos theta), as
  *          the absolute Z axis points down in the unit circle.
- * @param halfSizes Holds half the dimensions of the shape along the u and v vectors, respectively.
+ * @param halfSize Holds half the dimensions of the shape along the u and v vectors, respectively.
+ *
+ * @return true if @p point is inside the square with rotated X axis unit vector @p u and rotated Z axis unit vector @p v,
+ * and half dimensions specified by @p halfSizes.
  */
 bool PointIsInSquare(CFixedVector2D point, CFixedVector2D u, CFixedVector2D v, CFixedVector2D halfSize);
 
@@ -51,16 +53,18 @@ CFixedVector2D GetHalfBoundingBox(CFixedVector2D u, CFixedVector2D v, CFixedVect
 fixed DistanceToSquare(CFixedVector2D point, CFixedVector2D u, CFixedVector2D v, CFixedVector2D halfSize);
 
 /**
- * Returns the point that is closest to @p point on the edge of the square specified by orientation unit vectors @p u and @p v and half
+ * Find point closest to the given point on the edge of the given square or rectangle.
- * dimensions @p halfSize, relative to the center of the square. Currently assumes the @p u and @p v vectors are perpendicular.
- * Can also be used for rectangles.
  *
+ * @note Currently assumes the @p u and @p v vectors are perpendicular.
  * @param point point vector of the point we want to get the nearest edge point for, relative to the origin (center) of the shape.
  * @param u rotated X axis unit vector, relative to the absolute XZ plane. Indicates the orientation of the shape. If not rotated,
  *          this value is the absolute X axis unit vector (1,0). If rotated by angle theta, this should be (cos theta, -sin theta).
  * @param v rotated Z axis unit vector, relative to the absolute XZ plane. Indicates the orientation of the shape. If not rotated,
  *          this value is the absolute Z axis unit vector (0,1). If rotated by angle theta, this should be (sin theta, cos theta).
- * @param halfSizes Holds half the dimensions of the shape along the u and v vectors, respectively.
+ * @param halfSize Holds half the dimensions of the shape along the u and v vectors, respectively.
+ *
+ * @return point that is closest to @p point on the edge of the square specified by orientation unit vectors @p u and @p v and half
+ *	dimensions @p halfSize, relative to the center of the square
  */
 CFixedVector2D NearestPointOnSquare(CFixedVector2D point, CFixedVector2D u, CFixedVector2D v, CFixedVector2D halfSize);
 

source/simulation2/helpers/Render.h

@@ -57,23 +57,39 @@ namespace SimRender
 {
 
 /**
- * Updates @p overlay so that it represents the given line (a list of x, z coordinate pairs),
+ * Constructs overlay line from given points, conforming to terrain.
- * flattened on the terrain (or on the water if @p floating).
+ *
+ * @param[in] xz List of x,z coordinate pairs representing the line.
+ * @param[in,out] overlay Updated overlay line now conforming to terrain.
+ * @param[in] floating If true, the line conforms to water as well.
+ * @param[in] heightOffset Height above terrain to offset the line.
  */
 void ConstructLineOnGround(const CSimContext& context, const std::vector<float>& xz,
 		SOverlayLine& overlay,
 		bool floating, float heightOffset = 0.25f);
 
 /**
- * Updates @p overlay so that it represents the given circle, flattened on the terrain.
+ * Constructs overlay line as a circle with given center and radius, conforming to terrain.
+ *
+ * @param[in] x,z Coordinates of center of circle.
+ * @param[in] radius Radius of circle to construct.
+ * @param[in,out] overlay Updated overlay line representing this circle.
+ * @param[in] floating If true, the circle conforms to water as well.
+ * @param[in] heightOffset Height above terrain to offset the circle.
  */
 void ConstructCircleOnGround(const CSimContext& context, float x, float z, float radius,
 		SOverlayLine& overlay,
 		bool floating, float heightOffset = 0.25f);
 
 /**
- * Updates @p overlay so that it represents the given square, flattened on the terrain.
+ * Constructs overlay line as rectangle with given center and dimensions, conforming to terrain.
- * @p x and @p z are position of center, @p w and @p h are size of rectangle, @p a is clockwise angle.
+ *
+ * @param[in] x,z Coordinates of center of rectangle.
+ * @param[in] w,h Width/height dimensions of the rectangle.
+ * @param[in] a Clockwise angle to orient the rectangle.
+ * @param[in,out] overlay Updated overlay line representing this rectangle.
+ * @param[in] floating If true, the rectangle conforms to water as well.
+ * @param[in] heightOffset Height above terrain to offset the rectangle.
  */
 void ConstructSquareOnGround(const CSimContext& context, float x, float z, float w, float h, float a,
 		SOverlayLine& overlay,
@@ -81,53 +97,70 @@ void ConstructSquareOnGround(const CSimContext& context, float x, float z, float
 
 /**
  * Constructs a solid outline of an arbitrarily-aligned box.
+ *
+ * @param[in] box
+ * @param[in,out] overlayLine Updated overlay line representing the oriented box.
  */
 void ConstructBoxOutline(const CBoundingBoxOriented& box, SOverlayLine& overlayLine);
 
 /**
  * Constructs a solid outline of an axis-aligned bounding box.
+ *
+ * @param[in] bound
+ * @param[in,out] overlayLine Updated overlay line representing the AABB.
  */
 void ConstructBoxOutline(const CBoundingBoxAligned& bound, SOverlayLine& overlayLine);
 
 /**
- * Constructs a simple gimbal outline of radius @p radius at @p center in @p out.
+ * Constructs a simple gimbal outline with the given radius and center.
- * @param numSteps The amount of steps to trace a circle's complete outline. Must be a (strictly) positive multiple of four. 
+ *
+ * @param[in] center
+ * @param[in] radius
+ * @param[in,out] out Updated overlay line representing the gimbal.
+ * @param[in] numSteps The amount of steps to trace a circle's complete outline. Must be a (strictly) positive multiple of four. 
  *     For small radii, you can get away with small values; setting this to 4 will create a diamond shape.
  */
 void ConstructGimbal(const CVector3D& center, float radius, SOverlayLine& out, size_t numSteps = 16);
 
 /**
- * Constructs XYZ axis marker overlay lines for the coordinate system specified by @p coordSystem and writes them to @p outX,
+ * Constructs 3D axis marker overlay lines for the given coordinate system.
- * @p outY and @p outZ. The overlay lines are colored RGB for the XYZ axes, respectively.
+ * The overlay lines are colored RGB for the XYZ axes, respectively.
+ *
+ * @param[in] coordSystem Specifies the coordinate system.
+ * @param[out] outX,outY,outZ Constructed overlay lines for each axes.
  */
 void ConstructAxesMarker(const CMatrix3D& coordSystem, SOverlayLine& outX, SOverlayLine& outY, SOverlayLine& outZ);
 
 /**
- * Updates @p points so each point is averaged with its neighbours, resulting in
+ * Updates the given points so each point is averaged with its neighbours, resulting in
  * a somewhat smoother curve, assuming the points are roughly equally spaced.
- * If @p closed then the points are treated as a closed path (the last is connected
+ *
- * to the first).
+ * @param[in,out] points List of points to smooth.
+ * @param[in] closed if true, then the points are treated as a closed path (the last is connected
+ *	to the first).
  */
 void SmoothPointsAverage(std::vector<CVector2D>& points, bool closed);
 
 /**
- * Updates @p points to include intermediate points interpolating between the original
+ * Updates the given points to include intermediate points interpolating between the original
  * control points, using a rounded nonuniform spline.
- * The points are also shifted by @p offset in a direction 90 degrees clockwise from
+ *
- * the direction of the curve.
+ * @param[in,out] points List of points to interpolate.
- * If @p closed then the points are treated as a closed path (the last is connected
+ * @param[in] closed if true, then the points are treated as a closed path (the last is connected
- * to the first).
+ *	to the first).
- * @param segmentSamples Amount of intermediate points to sample between every two control points.
+ * @param[in] offset The points are shifted by this distance in a direction 90 degrees clockwise from
+ *	the direction of the curve.
+ * @param[in] segmentSamples Amount of intermediate points to sample between every two control points.
  */
 void InterpolatePointsRNS(std::vector<CVector2D>& points, bool closed, float offset, int segmentSamples = 4);
 
 /**
- * Creates a dashed line from the line specified by @points so that each dash is of length
+ * Creates a dashed line from the given line, dash length, and blank space between.
- * @p dashLength, and each blank inbetween is of length @p blankLength. The dashed line returned as a list of smaller lines
- * in @p dashedLineOut.
  *
- * @param dashLength Length of a single dash. Must be strictly positive.
+ * @param[in] linePoints List of points specifying the input line.
- * @param blankLength Length of a single blank between dashes. Must be strictly positive.
+ * @param[out] dashedLineOut The dashed line returned as a list of smaller lines
+ * @param[in] dashLength Length of a single dash. Must be strictly positive.
+ * @param[in] blankLength Length of a single blank between dashes. Must be strictly positive.
  */
 void ConstructDashedLine(const std::vector<CVector2D>& linePoints, SDashedLine& dashedLineOut, const float dashLength, const float blankLength);
 

source/simulation2/helpers/Selection.h

@@ -36,33 +36,50 @@ namespace EntitySelection
 
 /**
  * Finds all selectable entities under the given screen coordinates.
- * Returns list ordered by closeness of picking, closest first.
+ * 
- * Restricted to entities in the LOS of @p player, but with any owner.
+ * @param camera use this view to convert screen to world coordinates.
- * (For Atlas selections this value is ignored as the whole map is revealed).
+ * @param screenX,screenY 2D screen coordinates.
- * If @p allowEditorSelectables then all entities with the IID_Selectable interface
+ * @param player player whose LOS will be used when selecting entities. In Atlas
- * will be selected, else only selectable entities without the EditorOnly flag set.
+ *	this value is ignored as the whole map is revealed.
+ * @param allowEditorSelectables if true, all entities with the ICmpSelectable interface
+ *	will be selected (including decorative actors), else only those selectable ingame.
+ *
+ * @return ordered list of selected entities with the closest first.
  */
 std::vector<entity_id_t> PickEntitiesAtPoint(CSimulation2& simulation, const CCamera& camera, int screenX, int screenY, player_id_t player, bool allowEditorSelectables);
 
 /**
  * Finds all selectable entities within the given screen coordinate rectangle,
- * that belong to player @p owner.
+ * belonging to the given player. Used for bandboxing.
- * If @p owner is INVALID_PLAYER then ownership is ignored.
+ *
- * If @p allowEditorSelectables then all entities with the IID_Selectable interface
+ * @param camera use this view to convert screen to world coordinates.
- * will be selected, else only selectable entities without the EditorOnly flag set.
+ * @param sx0,sy0,sx1,sy1 diagonally opposite corners of the rectangle in 2D screen coordinates.
- * Returns unordered list.
+ * @param owner player whose entities we are selecting. Ownership is ignored if
+ *	INVALID_PLAYER is used.
+ * @param allowEditorSelectables if true, all entities with the ICmpSelectable interface
+ *	will be selected (including decorative actors), else only those selectable ingame.
+ *
+ * @return unordered list of selected entities.
  */
 std::vector<entity_id_t> PickEntitiesInRect(CSimulation2& simulation, const CCamera& camera, int sx0, int sy0, int sx1, int sy1, player_id_t owner, bool allowEditorSelectables);
 
 /**
- * Finds all entities with the given entity template name, that belong to player @p owner.
+ * Finds all entities with the given entity template name, belonging to the given player.
- * If @p owner is INVALID_PLAYER then ownership is ignored.
+ * 
- * If @p includeOffScreen then all entities visible in the world will be selected,
+ * @param camera use this view to convert screen to world coordinates.
- * else only entities visible on the screen will be selected.
+ * @param templateName the name of the template to match, or the selection group name
- * If @p matchRank then only entities that exactly match @p templateName will be selected,
+ *	for similar matching.
- * else entities with matching SelectionGroupName will be selected.
+ * @param owner player whose entities we are selecting. Ownership is ignored if
- * If @p allowEditorSelectables then all entities with the IID_Selectable interface
+ *	INVALID_PLAYER is used.
- * will be selected, else only selectable entities without the EditorOnly flag set.
+ * @param includeOffScreen if true, then all entities visible in the world will be selected,
+ *	else only entities visible to the camera will be selected.
+ * @param matchRank if true, only entities that exactly match templateName will be selected,
+ *	else entities with matching SelectionGroupName will be selected.
+ * @param allowEditorSelectables if true, all entities with the ICmpSelectable interface
+ *	will be selected (including decorative actors), else only those selectable ingame.
+ *
+ * @return unordered list of selected entities.
+ * @see ICmpIdentity
  */
 std::vector<entity_id_t> PickSimilarEntities(CSimulation2& simulation, const CCamera& camera, const std::string& templateName, player_id_t owner, bool includeOffScreen, bool matchRank, bool allowEditorSelectables);