From 8d5ddb9e346cbcac295997649877278db731dfd3 Mon Sep 17 00:00:00 2001 From: Alex Szpakowski Date: Mon, 23 Sep 2013 21:52:28 -0300 Subject: [PATCH] Fixed some internal documentation (thanks to clang's -Wdocumentation) --- src/common/Vector.h | 6 ++-- src/common/runtime.h | 2 +- src/modules/filesystem/physfs/File.h | 5 ++- src/modules/graphics/opengl/Font.h | 5 --- src/modules/graphics/opengl/Graphics.h | 2 +- src/modules/graphics/opengl/OpenGL.h | 2 +- src/modules/graphics/opengl/ParticleSystem.h | 31 ++++++++-------- src/modules/graphics/opengl/VertexBuffer.h | 6 ++-- src/modules/image/Image.h | 12 +++---- src/modules/keyboard/Keyboard.h | 4 +-- src/modules/math/BezierCurve.h | 2 +- src/modules/physics/box2d/Body.h | 38 ++++++++++---------- src/modules/physics/box2d/CircleShape.h | 6 ++-- src/modules/physics/box2d/Contact.h | 2 +- src/modules/physics/box2d/Physics.cpp | 6 ++-- src/modules/physics/box2d/Physics.h | 18 +++++----- src/modules/physics/box2d/PolygonShape.h | 6 ++-- src/modules/sound/Sound.h | 3 +- 18 files changed, 71 insertions(+), 85 deletions(-) diff --git a/src/common/Vector.h b/src/common/Vector.h index 93bfd932a..528fdaaae 100644 --- a/src/common/Vector.h +++ b/src/common/Vector.h @@ -81,7 +81,7 @@ public: /** * Gets a vector perpendicular to the Vector. * To get the true (normalized) normal, use v.getNormal(1.0f / v.getLength()) - * @param Scale factor to apply. + * @param scale factor to apply. * @return A normal to the Vector. **/ Vector getNormal(float scale) const; @@ -173,13 +173,13 @@ public: /** * Sets the x value of the Vector. - * @param The x value of the Vector. + * @param x The x value of the Vector. **/ void setX(float x); /** * Sets the x value of the Vector. - * @param The x value of the Vector. + * @param y The x value of the Vector. **/ void setY(float y); diff --git a/src/common/runtime.h b/src/common/runtime.h index 347ceda08..f922cba0f 100644 --- a/src/common/runtime.h +++ b/src/common/runtime.h @@ -463,7 +463,7 @@ T *luax_optmodule(lua_State *L, const char *k, love::bits type) * @param type The type bit. **/ template -T *luax_totype(lua_State *L, int idx, const char *, love::bits) +T *luax_totype(lua_State *L, int idx, const char * /* name */, love::bits /* type */) { return (T *)(((Proxy *)lua_touserdata(L, idx))->data); } diff --git a/src/modules/filesystem/physfs/File.h b/src/modules/filesystem/physfs/File.h index ac72e2476..ff82a4854 100644 --- a/src/modules/filesystem/physfs/File.h +++ b/src/modules/filesystem/physfs/File.h @@ -46,9 +46,8 @@ class File : public love::filesystem::File public: /** - * Constructs an File with the given source and filename. - * @param source The source from which to load the file. (Archive or directory) - * @param filename The relative filepath of the file to load from the source. + * Constructs an File with the given ilename. + * @param filename The relative filepath of the file to load. **/ File(const std::string &filename); diff --git a/src/modules/graphics/opengl/Font.h b/src/modules/graphics/opengl/Font.h index c8715cd44..3f44be37f 100644 --- a/src/modules/graphics/opengl/Font.h +++ b/src/modules/graphics/opengl/Font.h @@ -44,11 +44,6 @@ class Font : public Object, public Volatile { public: - /** - * Default constructor. - * - * @param data The font data to construct from. - **/ Font(love::font::Rasterizer *r, const Image::Filter &filter = Image::getDefaultFilter()); virtual ~Font(); diff --git a/src/modules/graphics/opengl/Graphics.h b/src/modules/graphics/opengl/Graphics.h index 4cb1fa32e..d171b286d 100644 --- a/src/modules/graphics/opengl/Graphics.h +++ b/src/modules/graphics/opengl/Graphics.h @@ -430,7 +430,7 @@ public: /** * Draws a polygon with an arbitrary number of vertices. - * @param type The type of drawing (line/filled). + * @param mode The type of drawing (line/filled). * @param coords Vertex components (x1, y1, x2, y2, etc.) * @param count Coord array size **/ diff --git a/src/modules/graphics/opengl/OpenGL.h b/src/modules/graphics/opengl/OpenGL.h index 8bd0342b6..58dd3e42a 100644 --- a/src/modules/graphics/opengl/OpenGL.h +++ b/src/modules/graphics/opengl/OpenGL.h @@ -137,7 +137,7 @@ public: * Helper for binding a texture to a specific texture unit. * * @param textureunit Index in the range of [0, maxtextureunits-1] - * @param resoreprev Restore previously bound texture unit when done. + * @param restoreprev Restore previously bound texture unit when done. **/ void bindTextureToUnit(GLuint texture, int textureunit, bool restoreprev); diff --git a/src/modules/graphics/opengl/ParticleSystem.h b/src/modules/graphics/opengl/ParticleSystem.h index 87f33d782..cc71af3ca 100644 --- a/src/modules/graphics/opengl/ParticleSystem.h +++ b/src/modules/graphics/opengl/ParticleSystem.h @@ -116,7 +116,6 @@ public: /** * Returns the current insert mode. - * @param mode The current insert mode. */ InsertMode getInsertMode() const; @@ -144,15 +143,15 @@ public: /** * Sets the life range of the particles. - * @param lifeMin The minimum life. - * @param lifeMax The maximum life (if 0, then becomes the same as minimum life). + * @param min The minimum life. + * @param max The maximum life (if 0, then becomes the same as minimum life). **/ void setParticleLifetime(float min, float max = 0); /** * Gets the lifetime of a particle. - * @param[out] min - * @param[out] max + * @param[out] min The minimum life. + * @param[out] max The maximum life. **/ void getParticleLifetime(float *min, float *max) const; @@ -229,8 +228,8 @@ public: /** * Gets the speed of the particles. - * @param[out] min - * @param[out] max + * @param[out] min The minimum speed. + * @param[out] max The maximum speed. **/ void getSpeed(float *min, float *max) const; @@ -272,8 +271,8 @@ public: /** * Gets the radial acceleration. - * @param[out] min - * @param[out] max + * @param[out] min The minimum amount of radial acceleration. + * @param[out] max The maximum amount of radial acceleration. **/ void getRadialAcceleration(float *min, float *max) const; @@ -292,8 +291,8 @@ public: /** * Gets the tangential acceleration. - * @param[out] min - * @param[out] max + * @param[out] min The minimum tangential acceleration. + * @param[out] max The maximum tangential acceleration. **/ void getTangentialAcceleration(float *min, float *max) const; @@ -339,9 +338,9 @@ public: void setRotation(float min, float max); /** - * Gets the initial amount of rotation of a particle. - * @param[out] min - * @param[out] max + * Gets the initial amount of rotation of a particle, in radians. + * @param[out] min The minimum initial rotation. + * @param[out] max The maximum initial rotation. **/ void getRotation(float *min, float *max) const; @@ -360,8 +359,8 @@ public: /** * Gets the amount of spin of a particle during its lifetime. - * @param[out] start - * @param[out] end + * @param[out] start The initial spin, in radians / s. + * @param[out] end The final spin, in radians / s. **/ void getSpin(float *start, float *end) const; diff --git a/src/modules/graphics/opengl/VertexBuffer.h b/src/modules/graphics/opengl/VertexBuffer.h index 6a4959d65..4e9c8f474 100644 --- a/src/modules/graphics/opengl/VertexBuffer.h +++ b/src/modules/graphics/opengl/VertexBuffer.h @@ -132,10 +132,8 @@ public: virtual void unmap() = 0; /** - * Bind the VertexBuffer to the specified target. - * (GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER). - * - * @param target GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_BUFFER. + * Bind the VertexBuffer to its specified target. + * (GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER, etc). */ virtual void bind() = 0; diff --git a/src/modules/image/Image.h b/src/modules/image/Image.h index a319affb1..096cca019 100644 --- a/src/modules/image/Image.h +++ b/src/modules/image/Image.h @@ -58,18 +58,18 @@ public: /** * Creates empty ImageData with the given size. - * @param The width of the ImageData. - * @param The height of the ImageData. + * @param width The width of the ImageData. + * @param height The height of the ImageData. * @return The new ImageData. **/ virtual ImageData *newImageData(int width, int height) = 0; /** * Creates empty ImageData with the given size. - * @param The width of the ImageData. - * @param The height of the ImageData. - * @param The data to load into the ImageData. - * @param Whether the new ImageData should take ownership of the data or + * @param width The width of the ImageData. + * @param height The height of the ImageData. + * @param data The data to load into the ImageData. + * @param own Whether the new ImageData should take ownership of the data or * copy it. * @return The new ImageData. **/ diff --git a/src/modules/keyboard/Keyboard.h b/src/modules/keyboard/Keyboard.h index 4a92180be..bf85c0c3e 100644 --- a/src/modules/keyboard/Keyboard.h +++ b/src/modules/keyboard/Keyboard.h @@ -248,8 +248,8 @@ public: virtual bool hasKeyRepeat() const = 0; /** - * Checks whether a certain key is down or not. - * @param key A key identifier. + * Checks whether certain keys are down or not. + * @param keylist An array of key identifiers, terminated by KEY_MAX_ENUM. * @return boolean **/ virtual bool isDown(Key *keylist) const = 0; diff --git a/src/modules/math/BezierCurve.h b/src/modules/math/BezierCurve.h index 3dccd5338..4f176248e 100644 --- a/src/modules/math/BezierCurve.h +++ b/src/modules/math/BezierCurve.h @@ -88,7 +88,7 @@ public: /** * Scale the curve. - * @param s Scale factor. + * @param phi Scale factor. * @param center Scale center. */ void scale(double phi, const Vector ¢er); diff --git a/src/modules/physics/box2d/Body.h b/src/modules/physics/box2d/Body.h index 69e6a66ba..a18db857c 100644 --- a/src/modules/physics/box2d/Body.h +++ b/src/modules/physics/box2d/Body.h @@ -91,29 +91,31 @@ public: /** * Gets the current position of the Body. - * @returns The current position. + * @param[out] x_o The x-component of the position. + * @param[out] y_o The y-component of the position. **/ void getPosition(float &x_o, float &y_o); /** * Gets the velocity in the current center of mass. - * @returns The velocity in the current center of mass. + * @param[out] x_o The x-component of the velocity. + * @param[out] y_o The y-component of the velocity. **/ void getLinearVelocity(float &x_o, float &y_o); /** * The current center of mass for the Body in world * coordinates. - * @returns The x-component of the point. - * @returns The y-component of the point. + * @param[out] x_o The x-component of the center of mass. + * @param[out] y_o The y-component of the center of mass. **/ void getWorldCenter(float &x_o, float &y_o); /** * The current center of mass for the Body in local * coordinates. - * @returns The x-component of the point. - * @returns The y-component of the point. + * @param[out] x_o The x-component of the center of mass. + * @param[out] y_o The y-component of the center of mass. **/ void getLocalCenter(float &x_o, float &y_o); @@ -269,8 +271,8 @@ public: * to world coordinates. * @param x The x-coordinate of the local point. * @param y The y-coordinate of the local point. - * @returns The x-coordinate of the point in world coordinates. - * @returns The y-coordinate of the point in world coordinates. + * @param[out] x_o The x-coordinate of the point in world coordinates. + * @param[out] y_o The y-coordinate of the point in world coordinates. **/ void getWorldPoint(float x, float y, float &x_o, float &y_o); @@ -279,8 +281,8 @@ public: * to world coordinates. * @param x The x-coordinate of the local vector. * @param y The y-coordinate of the local vector. - * @returns The x-coordinate of the vector in world coordinates. - * @returns The y-coordinate of the vector in world coordinates. + * @param[out] x_o The x-coordinate of the vector in world coordinates. + * @param[out] y_o The y-coordinate of the vector in world coordinates. **/ void getWorldVector(float x, float y, float &x_o, float &y_o); @@ -295,8 +297,8 @@ public: * to local coordinates. * @param x The x-coordinate of the world point. * @param y The y-coordinate of the world point. - * @returns The x-coordinate of the point in local coordinates. - * @returns The y-coordinate of the point in local coordinates. + * @param[out] x_o The x-coordinate of the point in local coordinates. + * @param[out] y_o The y-coordinate of the point in local coordinates. **/ void getLocalPoint(float x, float y, float &x_o, float &y_o); @@ -305,8 +307,8 @@ public: * to local coordinates. * @param x The x-coordinate of the world vector. * @param y The y-coordinate of the world vector. - * @returns The x-coordinate of the vector in local coordinates. - * @returns The y-coordinate of the vector in local coordinates. + * @param[out] x_o The x-coordinate of the vector in local coordinates. + * @param[out] y_o The y-coordinate of the vector in local coordinates. **/ void getLocalVector(float x, float y, float &x_o, float &y_o); @@ -314,8 +316,8 @@ public: * Gets the velocity on the Body for the given world point. * @param x The x-coordinate of the world point. * @param y The y-coordinate of the world point. - * @returns The x-component of the velocity vector. - * @returns The y-component of the velocity vector. + * @param[out] x_o The x-component of the velocity vector. + * @param[out] y_o The y-component of the velocity vector. **/ void getLinearVelocityFromWorldPoint(float x, float y, float &x_o, float &y_o); @@ -323,8 +325,8 @@ public: * Gets the velocity on the Body for the given local point. * @param x The x-coordinate of the local point. * @param y The y-coordinate of the local point. - * @returns The x-component of the velocity vector. - * @returns The y-component of the velocity vector. + * @param[out] x_o The x-component of the velocity vector. + * @param[out] y_o The y-component of the velocity vector. **/ void getLinearVelocityFromLocalPoint(float x, float y, float &x_o, float &y_o); diff --git a/src/modules/physics/box2d/CircleShape.h b/src/modules/physics/box2d/CircleShape.h index 34190fe28..d96a6fc1d 100644 --- a/src/modules/physics/box2d/CircleShape.h +++ b/src/modules/physics/box2d/CircleShape.h @@ -45,10 +45,8 @@ class CircleShape : public Shape public: /** - * Create a new CircleShape from the parent body and a - * Box2D CircleShape definition. - * @param body The parent body. - * @param def The CircleShape definition. + * Create a new CircleShape from the a Box2D CircleShape definition. + * @param c The CircleShape definition. **/ CircleShape(b2CircleShape *c, bool own = true); diff --git a/src/modules/physics/box2d/Contact.h b/src/modules/physics/box2d/Contact.h index 929627d28..0e026a2bc 100644 --- a/src/modules/physics/box2d/Contact.h +++ b/src/modules/physics/box2d/Contact.h @@ -53,7 +53,7 @@ public: * Creates a new Contact by copying a Box2D contact * point. It does not store the pointer, but copy the * data pointed to. - * @param point Pointer to the Box2D contact. + * @param contact Pointer to the Box2D contact. **/ Contact(b2Contact *contact); diff --git a/src/modules/physics/box2d/Physics.cpp b/src/modules/physics/box2d/Physics.cpp index 7880d0575..18b527ce3 100644 --- a/src/modules/physics/box2d/Physics.cpp +++ b/src/modules/physics/box2d/Physics.cpp @@ -274,10 +274,10 @@ int Physics::getDistance(lua_State *L) return 5; } -void Physics::setMeter(int meter) +void Physics::setMeter(int scale) { - if (meter < 1) throw love::Exception("Physics error: invalid meter"); - Physics::meter = meter; + if (scale < 1) throw love::Exception("Physics error: invalid meter"); + Physics::meter = scale; } int Physics::getMeter() diff --git a/src/modules/physics/box2d/Physics.h b/src/modules/physics/box2d/Physics.h index 877a76eb6..4e5f6317b 100644 --- a/src/modules/physics/box2d/Physics.h +++ b/src/modules/physics/box2d/Physics.h @@ -75,7 +75,7 @@ public: * Creates a new Body at the specified position. * @param world The world to create the Body in. * @param x The position along the x-axis. - * @param x The position along the y-axis. + * @param y The position along the y-axis. * @param type The type of body to create. **/ Body *newBody(World *world, float x, float y, Body::Type type); @@ -141,14 +141,12 @@ public: EdgeShape *newEdgeShape(float x1, float y1, float x2, float y2); /** - * Creates a new PolygonShape. - * @param ... A variable number of vertices. + * Creates a new PolygonShape from a variable number of vertices. **/ int newPolygonShape(lua_State *L); /** - * Creates a new ChainShape. - * @param ... A variable number of vertices. + * Creates a new ChainShape from a variable number of vertices. **/ int newChainShape(lua_State *L); @@ -272,13 +270,13 @@ public: /** * Sets the number of pixels in one meter. - * @param pixels The number of pixels in one meter. (1m ~= 3.3ft). + * @param scale The number of pixels in one meter. (1m ~= 3.3ft). **/ - static void setMeter(int meter); + static void setMeter(int scale); /** * Gets the number of pixels in one meter. - * @param pixels The number of pixels in one meter. (1m ~= 3.3ft). + * @return The number of pixels in one meter. (1m ~= 3.3ft). **/ static int getMeter(); @@ -326,14 +324,14 @@ public: /** * Scales a b2AABB down according to the current meter in pixels. - * @param v The unscaled input AABB. + * @param aabb The unscaled input AABB. * @return The scaled AABB. **/ static b2AABB scaleDown(const b2AABB &aabb); /** * Scales a b2AABB up according to the current meter in pixels. - * @param v The unscaled input AABB. + * @param aabb The unscaled input AABB. * @return The scaled AABB. **/ static b2AABB scaleUp(const b2AABB &aabb); diff --git a/src/modules/physics/box2d/PolygonShape.h b/src/modules/physics/box2d/PolygonShape.h index 5b25577e0..edb276fa7 100644 --- a/src/modules/physics/box2d/PolygonShape.h +++ b/src/modules/physics/box2d/PolygonShape.h @@ -43,10 +43,8 @@ class PolygonShape : public Shape public: /** - * Create a new PolygonShape from the parent Body and - * a Box2D polygon definition. - * @param body The parent Body. - * @param def The polygon definition. + * Create a new PolygonShape from a Box2D polygon definition. + * @param p The polygon definition. **/ PolygonShape(b2PolygonShape *p, bool own = true); diff --git a/src/modules/sound/Sound.h b/src/modules/sound/Sound.h index 6f2d04883..379779f4e 100644 --- a/src/modules/sound/Sound.h +++ b/src/modules/sound/Sound.h @@ -58,7 +58,7 @@ public: /** * Creates a new SoundData with the specified number of samples and format. - * @param duration In seconds. + * @param samples The number of samples. * @param sampleRate Number of samples per second. * @param bitDepth Bits per sample (8 or 16). * @param channels Either 1 for mono, or 2 for stereo. @@ -71,7 +71,6 @@ public: * specified file. * @param file The file with encoded sound data. * @param bufferSize The size of each decoded chunk. - * @param sampleRate Samples per second, or quality of the audio. 44100 is a good value. * @return A Decoder object on success, or zero if no decoder could be found. **/ virtual Decoder *newDecoder(filesystem::FileData *file, int bufferSize) = 0;