Updated the API documentation of the graphics module

sf::Image now uses GL_CLAMP_TO_EDGE instead of GL_CLAMP (removes black border when the image is smooth)

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1511 4e206d99-4929-0410-ac5d-dfc041789085

include/SFML/Graphics/Drawable.hpp

@@ -39,141 +39,207 @@ class Renderer;
 class RenderTarget;
 
 ////////////////////////////////////////////////////////////
-/// Enumerate the blending modes for drawable objects
+/// \brief Available blending modes for drawable objects
+///
 ////////////////////////////////////////////////////////////
 namespace Blend
 {
     enum Mode
     {
-        Alpha,    ///< Pixel = Src * a + Dest * (1 - a)
+        Alpha,    ///< Pixel = Src * Src.a + Dest * (1 - Src.a)
         Add,      ///< Pixel = Src + Dest
         Multiply, ///< Pixel = Src * Dest
-        None      ///< No blending
+        None      ///< Pixel = Src
     };
 }
 
 ////////////////////////////////////////////////////////////
-/// Abstract base class for every object that can be drawn
+/// \brief Abstract base class for objects that can be drawn
-/// into a render window
+///        to a render target
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Drawable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
-    /// \param position : Position of the object
+    /// \param position Position of the object
-    /// \param scale :    Scale factor
+    /// \param scale    Scale factor
-    /// \param rotation : Orientation, in degrees
+    /// \param rotation Orientation, in degrees
-    /// \param color :    Color of the object
+    /// \param color    Global color of the object
     ///
     ////////////////////////////////////////////////////////////
     Drawable(const Vector2f& position = Vector2f(0, 0), const Vector2f& scale = Vector2f(1, 1), float rotation = 0.f, const Color& color = Color(255, 255, 255));
 
     ////////////////////////////////////////////////////////////
-    /// Virtual destructor
+    /// \brief Virtual destructor
     ///
     ////////////////////////////////////////////////////////////
     virtual ~Drawable();
 
     ////////////////////////////////////////////////////////////
-    /// Set the position of the object (take 2 values)
+    /// \brief Set the position of the object
     ///
-    /// \param x : New X coordinate
+    /// This function completely overwrites the previous position.
-    /// \param y : New Y coordinate
+    /// See Move to apply an offset based on the previous position instead.
+    /// The default position of a drawable object is (0, 0).
+    ///
+    /// \param x X coordinate of the new position
+    /// \param y Y coordinate of the new position
+    ///
+    /// \see Move, SetX, SetY, GetPosition
     ///
     ////////////////////////////////////////////////////////////
     void SetPosition(float x, float y);
 
     ////////////////////////////////////////////////////////////
-    /// Set the position of the object (take a 2D vector)
+    /// \brief Set the position of the object
     ///
-    /// \param position : New position
+    /// This function completely overwrites the previous position.
+    /// See Move to apply an offset based on the previous position instead.
+    /// The default position of a drawable object is (0, 0).
+    ///
+    /// \param position New position
+    ///
+    /// \see Move, SetX, SetY, GetPosition
     ///
     ////////////////////////////////////////////////////////////
     void SetPosition(const Vector2f& position);
 
     ////////////////////////////////////////////////////////////
-    /// Set the X position of the object
+    /// \brief Set the X position of the object
     ///
-    /// \param x : New X coordinate
+    /// \param x New X coordinate
+    ///
+    /// \see SetY, SetPosition, GetPosition
     ///
     ////////////////////////////////////////////////////////////
     void SetX(float x);
 
     ////////////////////////////////////////////////////////////
-    /// Set the Y position of the object
+    /// \brief Set the Y position of the object
     ///
-    /// \param y : New Y coordinate
+    /// \param y New Y coordinate
+    ///
+    /// \see SetX, SetPosition, GetPosition
     ///
     ////////////////////////////////////////////////////////////
     void SetY(float y);
 
     ////////////////////////////////////////////////////////////
-    /// Set the scale of the object (take 2 values)
+    /// \brief Set the scale factors of the object
     ///
-    /// \param factorX : New horizontal scale (must be strictly positive)
+    /// \a factorX and \a factorY must be strictly positive,
-    /// \param factorY : New vertical scale (must be strictly positive)
+    /// otherwise they are ignored.
+    /// This function completely overwrites the previous scale.
+    /// See Scale to add a factor based on the previous scale instead.
+    /// The default scale of a drawable object is (1, 1).
+    ///
+    /// \param factorX New horizontal scale factor
+    /// \param factorY New vertical scale factor
+    ///
+    /// \see Scale, SetScaleX, SetScaleY, GetScale
     ///
     ////////////////////////////////////////////////////////////
     void SetScale(float factorX, float factorY);
 
     ////////////////////////////////////////////////////////////
-    /// Set the scale of the object (take a 2D vector)
+    /// \brief Set the scale factors of the object
     ///
-    /// \param Scale : New scale (both values must be strictly positive)
+    /// \a scale.x and \a scale.y must be strictly positive,
+    /// otherwise they are ignored.
+    /// This function completely overwrites the previous scale.
+    /// See Scale to add a factor based on the previous scale instead.
+    /// The default scale of a drawable object is (1, 1).
+    ///
+    /// \param scale New scale factors
+    ///
+    /// \see Scale, SetScaleX, SetScaleY, GetScale
     ///
     ////////////////////////////////////////////////////////////
     void SetScale(const Vector2f& scale);
 
     ////////////////////////////////////////////////////////////
-    /// Set the X scale factor of the object
+    /// \brief Set the X scale factor of the object
     ///
-    /// \param factor : New X scale factor
+    /// \a factor must be strictly positive, otherwise it is ignored.
+    ///
+    /// \param factor New horizontal scale factor
+    ///
+    /// \see SetScaleY, SetScale, GetScale
     ///
     ////////////////////////////////////////////////////////////
     void SetScaleX(float factor);
 
     ////////////////////////////////////////////////////////////
-    /// Set the Y scale factor of the object
+    /// \brief Set the Y scale factor of the object
     ///
-    /// \param factor : New Y scale factor
+    /// \a factor must be strictly positive, otherwise it is ignored.
+    ///
+    /// \param factor New vertical scale factor
+    ///
+    /// \see SetScaleX, SetScale, GetScale
     ///
     ////////////////////////////////////////////////////////////
     void SetScaleY(float factor);
 
     ////////////////////////////////////////////////////////////
-    /// Set the local origin of the object, in coordinates relative to the
+    /// \brief Set the local origin of the object
-    /// top-left of the object (take 2 values).
-    /// The default origin is (0, 0)
     ///
-    /// \param x : X coordinate of the origin
+    /// The origin of an object defines the center point for
-    /// \param y : Y coordinate of the origin
+    /// all transformations (position, scale, rotation).
+    /// The coordinates of this point must be relative to the
+    /// top-left corner of the object, and ignore all
+    /// transformations (position, scale, rotation).
+    /// The default origin of a drawable object is (0, 0).
+    ///
+    /// \param x X coordinate of the new origin
+    /// \param y Y coordinate of the new origin
+    ///
+    /// \see GetOrigin
     ///
     ////////////////////////////////////////////////////////////
     void SetOrigin(float x, float y);
 
     ////////////////////////////////////////////////////////////
-    /// Set the local origin of the object, in coordinates relative to the
+    /// \brief Set the local origin of the object
-    /// top-left of the object (take a 2D vector).
-    /// The default origin is (0, 0)
     ///
-    /// \param origin : New origin
+    /// The origin of an object defines the center point for
+    /// all transformations (position, scale, rotation).
+    /// The coordinates of this point must be relative to the
+    /// top-left corner of the object, and ignore all
+    /// transformations (position, scale, rotation).
+    /// The default origin of a drawable object is (0, 0).
+    ///
+    /// \param origin New origin
+    ///
+    /// \see GetOrigin
     ///
     ////////////////////////////////////////////////////////////
     void SetOrigin(const Vector2f& origin);
 
     ////////////////////////////////////////////////////////////
-    /// Set the orientation of the object
+    /// \brief Set the orientation of the object
     ///
-    /// \param angle : Angle of rotation, in degrees
+    /// This function completely overwrites the previous rotation.
+    /// See Rotate to add an angle based on the previous rotation instead.
+    /// The default rotation of a drawable object is 0.
+    ///
+    /// \param angle New rotation, in degrees
+    ///
+    /// \see Rotate, GetRotation
     ///
     ////////////////////////////////////////////////////////////
     void SetRotation(float angle);
 
     ////////////////////////////////////////////////////////////
-    /// Set the color of the object.
+    /// \brief Set the global color of the object
+    ///
+    /// This global color affects the entire object, and modulates
+    /// (multiplies) its original pixels.
+    ///
     /// The default color is white
     ///
     /// \param color : New color

include/SFML/Graphics/Font.hpp

@@ -294,7 +294,7 @@ private :
 /// \class sf::Font
 ///
 /// Fonts can be loaded from a file or from memory, from
-/// the most common types of fonts. See the LoadFromFile()
+/// the most common types of fonts. See the LoadFromFile
 /// function for the complete list of supported formats.
 ///
 /// Once it is loaded, a sf::Font instance provides three

include/SFML/Graphics/Glyph.hpp

@@ -35,14 +35,15 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Structure describing a glyph (a visual character)
+/// \brief Structure describing a glyph
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Glyph
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     Glyph() : Advance(0) {}
@@ -59,3 +60,19 @@ public :
 
 
 #endif // SFML_GLYPH_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Glyph
+///
+/// A glyph is the visual representation of a character.
+///
+/// The sf::Glyph structure provides the information needed
+/// to handle the glyph:
+/// \li its coordinates in the font's image
+/// \li its bounding rect
+/// \li the offset to apply to get the starting position of the next glyph
+///
+/// \see sf::Font
+///
+////////////////////////////////////////////////////////////

include/SFML/Graphics/Image.hpp

@@ -42,82 +42,115 @@ class RenderImage;
 class RenderWindow;
 
 ////////////////////////////////////////////////////////////
-/// Image is the low-level class for loading and
+/// \brief Class for loading, manipulating and saving images
-/// manipulating images
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Image : public Resource<Image>
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
+    ///
+    /// Creates an empty image.
     ///
     ////////////////////////////////////////////////////////////
     Image();
 
     ////////////////////////////////////////////////////////////
-    /// Copy constructor
+    /// \brief Copy constructor
     ///
-    /// \param copy : instance to copy
+    /// \param copy instance to copy
     ///
     ////////////////////////////////////////////////////////////
     Image(const Image& copy);
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~Image();
 
     ////////////////////////////////////////////////////////////
-    /// Load the image from a file
+    /// \brief Load the image from a file on disk
     ///
-    /// \param Filename : Path of the image file to load
+    /// The supported image formats are bmp, png, tga, jpg, dds
+    /// and psd. Some format options are not supported, like
+    /// progressive jpeg.
+    /// The maximum size for an image depends on the graphics
+    /// driver and can be retrieve with the GetMaximumSize function.
+    ///
+    /// \param filename Path of the image file to load
     ///
     /// \return True if loading was successful
     ///
+    /// \see LoadFromMemory, LoadFromPixels, SaveToFile
+    ///
     ////////////////////////////////////////////////////////////
     bool LoadFromFile(const std::string& filename);
 
     ////////////////////////////////////////////////////////////
-    /// Load the image from a file in memory
+    /// \brief Load the image from a file in memory
     ///
-    /// \param data :        Pointer to the file data in memory
+    /// The supported image formats are bmp, png, tga, jpg, dds
-    /// \param sizeInBytes : Size of the data to load, in bytes
+    /// and psd. Some format options are not supported, like
+    /// progressive jpeg.
+    /// The maximum size for an image depends on the graphics
+    /// driver and can be retrieve with the GetMaximumSize function.
+    ///
+    /// \param data Pointer to the file data in memory
+    /// \param size Size of the data to load, in bytes
     ///
     /// \return True if loading was successful
     ///
+    /// \see LoadFromFile, LoadFromPixels, SaveToFile
+    ///
     ////////////////////////////////////////////////////////////
-    bool LoadFromMemory(const void* data, std::size_t sizeInBytes);
+    bool LoadFromMemory(const void* data, std::size_t size);
 
     ////////////////////////////////////////////////////////////
-    /// Load the image directly from an array of pixels
+    /// \brief Load the image from an array of pixels
     ///
-    /// \param width :  Image width
+    /// The \a pixels argument must point to an array of 32 bits
-    /// \param height : Image height
+    /// RGBA pixels. In other words, the pixel array must have
-    /// \param pixels : Pointer to the pixels in memory (assumed format is RGBA)
+    /// this memory layout:
+    ///
+    /// [r0 g0 b0 a0 r1 g1 b1 a1 r2...]
+    ///
+    /// \param width  Width of the image
+    /// \param height Height of the image
+    /// \param pixels Pointer to the pixels in memory
     ///
     /// \return True if loading was successful
     ///
+    /// \see LoadFromFile, LoadFromMemory, SaveToFile
+    ///
     ////////////////////////////////////////////////////////////
     bool LoadFromPixels(unsigned int width, unsigned int height, const Uint8* pixels);
 
     ////////////////////////////////////////////////////////////
-    /// Save the content of the image to a file
+    /// \brief Save the image to a file on disk
     ///
-    /// \param filename : Path of the file to save (overwritten if already exist)
+    /// The format of the image is automatically deduced from
+    /// the extension. The supported image formats are bmp, png,
+    /// tga, jpg, dds and psd. The destination file is overwritten
+    /// if it already exists.
+    ///
+    /// \param filename Path of the file to save
     ///
     /// \return True if saving was successful
     ///
+    /// \see LoadFromFile, LoadFromMemory, LoadFromPixels
+    ///
     ////////////////////////////////////////////////////////////
     bool SaveToFile(const std::string& filename) const;
 
     ////////////////////////////////////////////////////////////
-    /// Create an empty image
+    /// \brief Create the image and fill it with a unique color
     ///
-    /// \param width :  Image width
+    /// \param width  Width of the image
-    /// \param height : Image height
+    /// \param height Height of the image
-    /// \param color :  Image color
+    /// \param color  Fill color
     ///
     /// \return True if creation was successful
     ///
@@ -125,34 +158,49 @@ public :
     bool Create(unsigned int width, unsigned int height, const Color& color = Color(0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Create transparency mask from a specified colorkey
+    /// \brief Create a transparency mask from a specified colorkey
     ///
-    /// \param color : Color to become transparent
+    /// This function sets the alpha value of every pixel matching
-    /// \param alpha : Alpha value to assign to transparent pixels
+    /// the given color to \a alpha (0 by default), so that they
+    /// become transparent.
+    ///
+    /// \param color Color to make transparent
+    /// \param alpha Alpha value to assign to transparent pixels
     ///
     ////////////////////////////////////////////////////////////
     void CreateMaskFromColor(const Color& color, Uint8 alpha = 0);
 
     ////////////////////////////////////////////////////////////
-    /// Copy pixels from another image onto this one.
+    /// \brief Copy pixels from another image onto this one
-    /// This function does a slow pixel copy and should only
-    /// be used at initialization time
     ///
-    /// \param source :     Source image to copy
+    /// This function does a slow pixel copy and should only
-    /// \param destX :      X coordinate of the destination position
+    /// be used at initialization time. It can be used to prepare
-    /// \param destY :      Y coordinate of the destination position
+    /// a complex static image from several others, but if you
-    /// \param sourceRect : Sub-rectangle of the source image to copy
+    /// need this kind of feature in real-time you'd better use
-    /// \param applyAlpha : Should the copy take in account the source transparency?
+    /// sf::RenderImage.
+    /// If \a sourceRect is empty, the whole image is copied.
+    /// If \a applyAlpha is set to true, the transparency of
+    /// source pixels is applied. If it is false, the pixels are
+    /// copied unchanged with their alpha value.
+    ///
+    /// \param source     Source image to copy
+    /// \param destX      X coordinate of the destination position
+    /// \param destY      Y coordinate of the destination position
+    /// \param sourceRect Sub-rectangle of the source image to copy
+    /// \param applyAlpha Should the copy take in account the source transparency?
     ///
     ////////////////////////////////////////////////////////////
     void Copy(const Image& source, unsigned int destX, unsigned int destY, const IntRect& sourceRect = IntRect(0, 0, 0, 0), bool applyAlpha = false);
 
     ////////////////////////////////////////////////////////////
-    /// Create the image from the current contents of the
+    /// \brief Copy the contents of a window to the image
-    /// given window
     ///
-    /// \param window :     Window to capture
+    /// If \a sourceRect is empty, the whole window is copied.
-    /// \param sourceRect : Sub-rectangle of the screen to copy (empty by default - entire image)
+    /// Warning: this is a slow operation, if you need to draw
+    /// dynamic contents to an image then use sf::RenderImage.
+    ///
+    /// \param window     Window to capture
+    /// \param sourceRect Sub-rectangle of the screen to copy
     ///
     /// \return True if copy was successful
     ///
@@ -160,30 +208,44 @@ public :
     bool CopyScreen(RenderWindow& window, const IntRect& sourceRect = IntRect(0, 0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Change the color of a pixel
+    /// \brief Change the color of a pixel
     ///
-    /// \param x :     X coordinate of pixel in the image
+    /// This function doesn't check the validity of the pixel
-    /// \param y :     Y coordinate of pixel in the image
+    /// coordinates, using out-of-range values will result in
-    /// \param color : New color for pixel (x, y)
+    /// an undefined behaviour.
+    ///
+    /// \param x      X coordinate of pixel to change
+    /// \param y      Y coordinate of pixel to change
+    /// \param color  New color of the pixel
+    ///
+    /// \see GetPixel
     ///
     ////////////////////////////////////////////////////////////
     void SetPixel(unsigned int x, unsigned int y, const Color& color);
 
     ////////////////////////////////////////////////////////////
-    /// Get a pixel from the image
+    /// \brief Get the color of a pixel
     ///
-    /// \param x : X coordinate of pixel in the image
+    /// This function doesn't check the validity of the pixel
-    /// \param y : Y coordinate of pixel in the image
+    /// coordinates, using out-of-range values will result in
+    /// an undefined behaviour.
     ///
-    /// \return Color of pixel (x, y)
+    /// \param x X coordinate of pixel to get
+    /// \param y Y coordinate of pixel to get
+    ///
+    /// \return Color of the pixel at coordinates (x, y)
     ///
     ////////////////////////////////////////////////////////////
     Color GetPixel(unsigned int x, unsigned int y) const;
 
     ////////////////////////////////////////////////////////////
-    /// Get a read-only pointer to the array of pixels (RGBA 8 bits integers components)
+    /// \brief Get a read-only pointer to the array of pixels
-    /// Array size is GetWidth() x GetHeight() x 4
+    ///
-    /// This pointer becomes invalid if you reload or resize the image
+    /// The returned value points to an array of RGBA pixels made of
+    /// 8 bits integers components. The size of the array is
+    /// width * height * 4.
+    /// Warning: the returned pointer may become invalid if you
+    /// modify the image, so you should never store it for too long.
     ///
     /// \return Const pointer to the array of pixels
     ///
@@ -191,79 +253,112 @@ public :
     const Uint8* GetPixelsPtr() const;
 
     ////////////////////////////////////////////////////////////
-    /// Update the whole image from an array of pixels
+    /// \brief Update the whole image from an array of pixels
     ///
-    /// \param pixels : Array of pixels to write to the image
+    /// The \a pixels array is assumed to have the same size as
+    /// the image, and to store RGBA 32 bits pixels.
+    /// See the other overload of this function to update only
+    /// a sub-rectangle of the image.
+    ///
+    /// \param pixels Array of pixels to write to the image
     ///
     ////////////////////////////////////////////////////////////
     void UpdatePixels(const Uint8* pixels);
 
     ////////////////////////////////////////////////////////////
-    /// Update a sub-rectangle of the image from an array of pixels
+    /// \brief Update a sub-rectangle of the image from an array of pixels
     ///
+    /// The \a pixels array is assumed to store RGBA 32 bits pixels.
     /// Warning: for performances reasons, this function doesn't
     /// perform any check; thus you're responsible of ensuring that
     /// \a rectangle does not exceed the image size, and that
     /// \a pixels contains enough elements.
+    /// See the other overload of this function to update the
+    /// whole image.
     ///
-    /// \param rectangle : Sub-rectangle of the image to update
+    /// \param rectangle Sub-rectangle of the image to update
-    /// \param pixels :    Array of pixels to write to the image
+    /// \param pixels    Array of pixels to write to the image
     ///
     ////////////////////////////////////////////////////////////
     void UpdatePixels(const Uint8* pixels, const IntRect& rectangle);
 
     ////////////////////////////////////////////////////////////
-    /// Bind the image for rendering
+    /// \brief Activate the image for rendering
+    ///
+    /// This function is mainly used internally by the SFML
+    /// render system. However it can be useful when
+    /// using sf::Image together with OpenGL code (it calls
+    /// glBindTexture).
     ///
     ////////////////////////////////////////////////////////////
     void Bind() const;
 
     ////////////////////////////////////////////////////////////
-    /// Enable or disable image smooth filter.
+    /// \brief Enable or disable the smooth filter
-    /// This parameter is enabled by default
     ///
-    /// \param smooth : True to enable smoothing filter, false to disable it
+    /// When the filter is activated, the image appears smoother
+    /// so that pixels are less noticeable. However if you want
+    /// the image to look exactly the same as its source file, you
+    /// should disable it.
+    /// The smooth filter is enabled by default.
+    ///
+    /// \param smooth True to enable smoothing, false to disable it
+    ///
+    /// \see IsSmooth
     ///
     ////////////////////////////////////////////////////////////
     void SetSmooth(bool smooth);
 
     ////////////////////////////////////////////////////////////
-    /// Return the width of the image
+    /// \brief Tell whether the smooth filter is enabled or not
     ///
-    /// \return Width in pixels
+    /// \return True if smoothing is enabled, false if it is disabled
     ///
-    ////////////////////////////////////////////////////////////
+    /// \see SetSmooth
-    unsigned int GetWidth() const;
-
-    ////////////////////////////////////////////////////////////
-    /// Return the height of the image
-    ///
-    /// \return Height in pixels
-    ///
-    ////////////////////////////////////////////////////////////
-    unsigned int GetHeight() const;
-
-    ////////////////////////////////////////////////////////////
-    /// Tells whether the smooth filtering is enabled or not
-    ///
-    /// \return True if image smoothing is enabled
     ///
     ////////////////////////////////////////////////////////////
     bool IsSmooth() const;
 
     ////////////////////////////////////////////////////////////
-    /// Convert a subrect expressed in pixels, into float
+    /// \brief Return the width of the image
-    /// texture coordinates
     ///
-    /// \param rectangle : Sub-rectangle of image to convert
+    /// \return Width in pixels
     ///
-    /// \return Texture coordinates corresponding to the sub-rectangle
+    /// \see GetHeight
+    ///
+    ////////////////////////////////////////////////////////////
+    unsigned int GetWidth() const;
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Return the height of the image
+    ///
+    /// \return Height in pixels
+    ///
+    /// \see GetWidth
+    ///
+    ////////////////////////////////////////////////////////////
+    unsigned int GetHeight() const;
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Convert a rectangle of pixels into texture coordinates
+    ///
+    /// This function is used by code that needs to map the image
+    /// to some OpenGL geometry. It converts the source rectangle,
+    /// expressed in pixels, to float coordinates in the range [0, 1].
+    ///
+    /// \param rectangle Rectangle to convert
+    ///
+    /// \return Texture coordinates corresponding to \a rectangle
     ///
     ////////////////////////////////////////////////////////////
     FloatRect GetTexCoords(const IntRect& rectangle) const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the maximum image size according to hardware support
+    /// \brief Get the maximum image size allowed
+    ///
+    /// This maximum size is defined by the graphics driver.
+    /// You can expect a value of 512 pixels for low-end graphics
+    /// card, and up to 8192 pixels for newer hardware.
     ///
     /// \return Maximum size allowed for images, in pixels
     ///
@@ -271,21 +366,11 @@ public :
     static unsigned int GetMaximumSize();
 
     ////////////////////////////////////////////////////////////
-    /// Get a valid image size according to hardware support
+    /// \brief Overload of assignment operator
     ///
-    /// \param Size : size to convert
+    /// \param right Instance to assign
     ///
-    /// \return Valid nearest size (greater than or equal to specified size)
+    /// \return Reference to self
-    ///
-    ////////////////////////////////////////////////////////////
-    static unsigned int GetValidSize(unsigned int size);
-
-    ////////////////////////////////////////////////////////////
-    /// Assignment operator
-    ///
-    /// \param other : instance to assign
-    ///
-    /// \return Reference to the image
     ///
     ////////////////////////////////////////////////////////////
     Image& operator =(const Image& other);
@@ -296,7 +381,22 @@ private :
     friend class RenderImage;
 
     ////////////////////////////////////////////////////////////
-    /// Create the OpenGL texture
+    /// \brief Get a valid image size according to hardware support
+    ///
+    /// This function checks whether the graphics driver supports
+    /// non power of two sizes or not, and adjusts the size
+    /// accordingly.
+    /// The returned size is greater than or equal to the original size.
+    ///
+    /// \param Size size to convert
+    ///
+    /// \return Valid nearest size (greater than or equal to specified size)
+    ///
+    ////////////////////////////////////////////////////////////
+    static unsigned int GetValidSize(unsigned int size);
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Create the OpenGL texture
     ///
     /// \return True if texture has been successfully created
     ///
@@ -304,33 +404,33 @@ private :
     bool CreateTexture();
 
     ////////////////////////////////////////////////////////////
-    /// Make sure the texture in video memory is updated with the
+    /// \brief Make sure that the texture in video memory is
-    /// array of pixels
+    ///        synchronized with the pixels cache
     ///
     ////////////////////////////////////////////////////////////
     void EnsureTextureUpdate() const;
 
     ////////////////////////////////////////////////////////////
-    /// Make sure the array of pixels is updated with the
+    /// \brief Make sure the pixels cache is synchronized with
-    /// texture in video memory
+    ///        the texture in video memory
     ///
     ////////////////////////////////////////////////////////////
     void EnsureArrayUpdate() const;
 
     ////////////////////////////////////////////////////////////
-    /// Make sure that the image is ready to be used
+    /// \brief Make sure that the image is ready to be used
     ///
     ////////////////////////////////////////////////////////////
     void Use() const;
 
     ////////////////////////////////////////////////////////////
-    /// Reset the image attributes
+    /// \brief Reset the image attributes and leave a clean empty image
     ///
     ////////////////////////////////////////////////////////////
     void Reset();
 
     ////////////////////////////////////////////////////////////
-    /// Destroy the OpenGL texture
+    /// \brief Destroy the OpenGL texture
     ///
     ////////////////////////////////////////////////////////////
     void DestroyTexture();
@@ -359,3 +459,54 @@ private :
 
 
 #endif // SFML_IMAGE_HPP
+
+
+////////////////////////////////////////////////////////////
+/// \class sf::Image
+///
+/// sf::Image is an abstraction to manipulate images
+/// as bidimensional arrays of pixels. The class provides
+/// functions to load, read, write and save pixels, as well
+/// as many other useful functions to...
+///
+/// sf::Image can handle a unique internal representation of
+/// pixels, which is RGBA 32 bits. This means that a pixel
+/// must be composed of 8 bits red, green, blue and alpha
+/// channels -- just like a sf::Color.
+/// All the functions that return an array of pixels follow
+/// this rule, and all parameters that you pass to sf::Image
+/// functions (such as LoadFromPixels or UpdatePixels) must
+/// use this representation as well.
+///
+/// A sf::Image can be copied, but it is a heavy resource and
+/// if possible you should always use [const] references to
+/// pass or return them to avoid useless copies.
+///
+/// Usage example:
+/// \code
+/// // Load an image file
+/// sf::Image background;
+/// if (!background.LoadFromFile("background.jpg"))
+///     return -1;
+///
+/// // Create a 20x20 image filled with black color
+/// sf::Image image;
+/// if (!image.Create(20, 20, sf::Color::Black))
+///     return -1;
+///
+/// // Copy image1 on image2 at position (10, 10)
+/// image.Copy(background, 10, 10);
+///
+/// // Make the top-left pixel transparent
+/// sf::Color color = image.GetPixel(0, 0);
+/// color.a = 0;
+/// image.SetPixel(0, 0, color);
+///
+/// // Save the image to a file
+/// if (!image.SaveToFile("result.png"))
+///     return -1;
+/// \endcode
+///
+/// \see sf::Sprite
+///
+////////////////////////////////////////////////////////////

include/SFML/Graphics/Shape.hpp

@@ -36,42 +36,48 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Shape defines a drawable convex shape ; it also defines
+/// \brief A convex, colored polygon with an optional outline
-/// helper functions to draw simple shapes like
+///
-/// lines, rectangles, circles, etc.
 ////////////////////////////////////////////////////////////
 class SFML_API Shape : public Drawable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
+    ///
+    /// Creates an empty shape (no point).
     ///
     ////////////////////////////////////////////////////////////
     Shape();
 
     ////////////////////////////////////////////////////////////
-    /// Add a point to the shape
+    /// \brief Add a new point to the shape
     ///
-    /// \param x, y :         Position of the point
+    /// The new point is inserted at the end of the shape.
-    /// \param color :        Color of the point
+    ///
-    /// \param outlineColor : Outline color of the point
+    /// \param x            X position of the point
+    /// \param y            Y position of the point
+    /// \param color        Color of the point
+    /// \param outlineColor Outline color of the point
     ///
     ////////////////////////////////////////////////////////////
     void AddPoint(float x, float y, const Color& color = Color(255, 255, 255), const Color& outlineColor = Color(0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Add a point to the shape
+    /// \brief Add a new point to the shape
     ///
-    /// \param position :     Position of the point
+    /// The new point is inserted at the end of the shape.
-    /// \param color :        Color of the point
+    ///
-    /// \param outlineColor : Outline color of the point
+    /// \param position     Position of the point
+    /// \param color        Color of the point
+    /// \param outlineColor Outline color of the point
     ///
     ////////////////////////////////////////////////////////////
     void AddPoint(const Vector2f& position, const Color& color = Color(255, 255, 255), const Color& outlineColor = Color(0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Get the number of points composing the shape
+    /// \brief Get the number of points composing the shape
     ///
     /// \param Total number of points
     ///
@@ -79,175 +85,284 @@ public :
     unsigned int GetPointsCount() const;
 
     ////////////////////////////////////////////////////////////
-    /// Enable or disable filling the shape.
+    /// \brief Enable or disable the shape's filling
-    /// Fill is enabled by default
     ///
-    /// \param enable : True to enable, false to disable
+    /// This option is enabled by default.
+    ///
+    /// \param enable True to enable, false to disable
+    ///
+    /// \see EnableOutline
     ///
     ////////////////////////////////////////////////////////////
     void EnableFill(bool enable);
 
     ////////////////////////////////////////////////////////////
-    /// Enable or disable drawing the shape outline.
+    /// \brief Enable or disable the shape's outline
-    /// Outline is enabled by default
     ///
-    /// \param enable : True to enable, false to disable
+    /// This option is enabled by default.
+    ///
+    /// \param enable True to enable, false to disable
+    ///
+    /// \see EnableFill
     ///
     ////////////////////////////////////////////////////////////
     void EnableOutline(bool enable);
 
     ////////////////////////////////////////////////////////////
-    /// Set the position of a point
+    /// \brief Change the position of a point
     ///
-    /// \param index :    Index of the point, in range [0, GetPointsCount() - 1]
+    /// Warning: this function doesn't check the validity of
-    /// \param position : New position of the index-th point
+    /// \a index, if it is out of bounds (ie. in the range
+    /// [0, GetPointscount() - 1]) the behaviour is undefined.
+    ///
+    /// \param index    Index of the point
+    /// \param position New position of the point
+    ///
+    /// \see GetPointPosition, SetPointColor, SetPointOutlineColor
     ///
     ////////////////////////////////////////////////////////////
     void SetPointPosition(unsigned int index, const Vector2f& position);
 
     ////////////////////////////////////////////////////////////
-    /// Set the position of a point
+    /// \brief Change the position of a point
     ///
-    /// \param index : Index of the point, in range [0, GetPointsCount() - 1]
+    /// Warning: this function doesn't check the validity of
-    /// \param x :     New X coordinate of the index-th point
+    /// \a index, if it is out of bounds (ie. in the range
-    /// \param y :     New Y coordinate of the index-th point
+    /// [0, GetPointscount() - 1]) the behaviour is undefined.
+    ///
+    /// \param index Index of the point
+    /// \param x     New X coordinate of the point
+    /// \param y     New Y coordinate of the point
+    ///
+    /// \see GetPointPosition, SetPointColor, SetPointOutlineColor
     ///
     ////////////////////////////////////////////////////////////
     void SetPointPosition(unsigned int index, float x, float y);
 
     ////////////////////////////////////////////////////////////
-    /// Set the color of a point
+    /// \brief Change the color of a point
     ///
-    /// \param index : Index of the point, in range [0, GetPointsCount() - 1]
+    /// Warning: this function doesn't check the validity of
-    /// \param color : New color of the index-th point
+    /// \a index, if it is out of bounds (ie. in the range
+    /// [0, GetPointscount() - 1]) the behaviour is undefined.
+    ///
+    /// \param index Index of the point
+    /// \param color New color of the point
+    ///
+    /// \see GetPointColor, SetPointPosition, SetPointOutlineColor
     ///
     ////////////////////////////////////////////////////////////
     void SetPointColor(unsigned int index, const Color& color);
 
     ////////////////////////////////////////////////////////////
-    /// Set the outline color of a point
+    /// \brief Change the outline color of a point
     ///
-    /// \param index :       Index of the point, in range [0, GetPointsCount() - 1]
+    /// Warning: this function doesn't check the validity of
-    /// \param outlineColor : New outline color of the index-th point
+    /// \a index, if it is out of bounds (ie. in the range
+    /// [0, GetPointscount() - 1]) the behaviour is undefined.
+    ///
+    /// \param index Index of the point
+    /// \param color New outline color of the point
+    ///
+    /// \see GetPointOutlineColor, SetPointPosition, SetPointColor
     ///
     ////////////////////////////////////////////////////////////
-    void SetPointOutlineColor(unsigned int index, const Color& outlineColor);
+    void SetPointOutlineColor(unsigned int index, const Color& color);
 
     ////////////////////////////////////////////////////////////
-    /// Change the width of the shape outline
+    /// \brief Change the thickness of the shape outline
     ///
-    /// \param width : New width
+    /// \param width New width of the outline
+    ///
+    /// \see GetOutlineWidth, EnableOutline
     ///
     ////////////////////////////////////////////////////////////
     void SetOutlineWidth(float width);
 
     ////////////////////////////////////////////////////////////
-    /// Get the position of a point
+    /// \brief Get the position of a point
     ///
-    /// \param index : Index of the point, in range [0, GetPointsCount() - 1]
+    /// Warning: this function doesn't check the validity of
+    /// \a index, if it is out of bounds (ie. in the range
+    /// [0, GetPointscount() - 1]) the behaviour is undefined.
+    ///
+    /// \param index Index of the point
     ///
     /// \return Position of the index-th point
     ///
+    /// \see SetPointPosition, GetPointColor, GetPointOutlineColor
+    ///
     ////////////////////////////////////////////////////////////
     const Vector2f& GetPointPosition(unsigned int index) const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the color of a point
+    /// \brief Get the color of a point
     ///
-    /// \param Index : index of the point, in range [0, GetPointsCount() - 1]
+    /// Warning: this function doesn't check the validity of
+    /// \a index, if it is out of bounds (ie. in the range
+    /// [0, GetPointscount() - 1]) the behaviour is undefined.
+    ///
+    /// \param Index index of the point
     ///
     /// \return Color of the index-th point
     ///
+    /// \see SetPointColor, GetPointPosition, GetPointOutlineColor
+    ///
     ////////////////////////////////////////////////////////////
     const Color& GetPointColor(unsigned int index) const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the outline color of a point
+    /// \brief Get the outline color of a point
     ///
-    /// \param index : Index of the point, in range [0, GetPointsCount() - 1]
+    /// Warning: this function doesn't check the validity of
+    /// \a index, if it is out of bounds (ie. in the range
+    /// [0, GetPointscount() - 1]) the behaviour is undefined.
+    ///
+    /// \param index Index of the point
     ///
     /// \return Outline color of the index-th point
     ///
+    /// \see SetPointOutlineColor, GetPointPosition, GetPointColor
+    ///
     ////////////////////////////////////////////////////////////
     const Color& GetPointOutlineColor(unsigned int index) const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the width of the shape outline
+    /// \brief Get the thickness of the shape outline
     ///
     /// \return Current outline width
     ///
+    /// \see SetOutlineWidth
+    ///
     ////////////////////////////////////////////////////////////
     float GetOutlineWidth() const;
 
     ////////////////////////////////////////////////////////////
-    /// Create a shape made of a single line (use floats)
+    /// \brief Create a new line
     ///
-    /// \param p1x, p1y :     Position of the first point
+    /// This is a static function that returns a new object,
-    /// \param p2x, p2y :     Position second point
+    /// don't try to call it on an existing object to modify it.
-    /// \param thickness :    Line thickness
+    /// \begincode
-    /// \param color :        Color used to draw the line
+    /// sf::Shape line = sf::Shape::Line(0, 0, 10, 20, 2.5f, sf::Color::Green);
-    /// \param outline :      Outline width
+    /// \endcode
-    /// \param outlineColor : Color used to draw the outline
+    ///
+    /// \param x0           X coordinate of the start point
+    /// \param y0           Y coordinate of the start point
+    /// \param x1           X coordinate of the end point
+    /// \param y1           Y coordinate of the end point
+    /// \param thickness    Thickness of the line
+    /// \param color        Color of the shape's points
+    /// \param outline      Outline width
+    /// \param outlineColor Outline color of the shape's points
+    ///
+    /// \see Rectangle, Circle
     ///
     ////////////////////////////////////////////////////////////
     static Shape Line(float p1x, float p1y, float p2x, float p2y, float thickness, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Create a shape made of a single line (use vectors)
+    /// \brief Create a new line
     ///
-    /// \param p1 :           Position of the first point
+    /// This is a static function that returns a new object,
-    /// \param p2 :           Position second point
+    /// don't try to call it on an existing object to modify it.
-    /// \param thickness :    Line thickness
+    /// \begincode
-    /// \param color :        Color used to draw the line
+    /// sf::Vector2f start(0, 0);
-    /// \param outline :      Outline width
+    /// sf::Vector2f end(10, 20);
-    /// \param outlineColor : Color used to draw the outline
+    /// sf::Shape line = sf::Shape::Line(start, end, 2.5f, sf::Color::Green);
+    /// \endcode
+    ///
+    /// \param start        Start point
+    /// \param end          End point
+    /// \param thickness    Thickness of the line
+    /// \param color        Color of the shape's points
+    /// \param outline      Outline width
+    /// \param outlineColor Outline color of the shape's points
+    ///
+    /// \see Rectangle, Circle
     ///
     ////////////////////////////////////////////////////////////
-    static Shape Line(const Vector2f& p1, const Vector2f& p2, float thickness, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
+    static Shape Line(const Vector2f& start, const Vector2f& end, float thickness, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Create a shape made of a single rectangle
+    /// \brief Create a new rectangular shape
     ///
-    /// \param left, top :     Position of the top-left corner
+    /// This is a static function that returns a new object,
-    /// \param width, height : Size of the rectangle
+    /// don't try to call it on an existing object to modify it.
-    /// \param color :         Color used to fill the rectangle
+    /// \begincode
-    /// \param outline :       Outline width
+    /// sf::Shape rect = sf::Shape::Rectangle(10, 20, 50, 100, sf::Color::Red);
-    /// \param outlineColor :  Color used to draw the outline
+    /// \endcode
+    ///
+    /// \param left         Left coordinate of the rectangle
+    /// \param top          Top coordinate of the rectangle
+    /// \param width        Width of the rectangle
+    /// \param height       Height of the rectangle
+    /// \param color        Color of the shape's points
+    /// \param outline      Outline width
+    /// \param outlineColor Outline color of the shape's points
+    ///
+    /// \see Line, Circle
     ///
     ////////////////////////////////////////////////////////////
     static Shape Rectangle(float left, float top, float width, float height, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Create a shape made of a single rectangle
+    /// \brief Create a new rectangular shape
     ///
-    /// \param rectangle :    Rectangle
+    /// This is a static function that returns a new object,
-    /// \param color :        Color used to fill the rectangle
+    /// don't try to call it on an existing object to modify it.
-    /// \param outline :      Outline width
+    /// \begincode
-    /// \param outlineColor : Color used to draw the outline
+    /// sf::FloatRect source(10, 20, 50, 100);
+    /// sf::Shape rect = sf::Shape::Rectangle(source, sf::Color::Red);
+    /// \endcode
+    ///
+    /// \param rectangle    Rectangle defining the shape
+    /// \param color        Color of the shape's points
+    /// \param outline      Outline width
+    /// \param outlineColor Outline color of the shape's points
+    ///
+    /// \see Line, Circle
     ///
     ////////////////////////////////////////////////////////////
     static Shape Rectangle(const FloatRect& rectangle, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Create a shape made of a single circle (use floats)
+    /// \brief Create a new circular shape
     ///
-    /// \param x, y :         Position of the center
+    /// This is a static function that returns a new object,
-    /// \param radius :       Radius
+    /// don't try to call it on an existing object to modify it.
-    /// \param color :        Color used to fill the circle
+    /// \begincode
-    /// \param outline :      Outline width
+    /// sf::Shape circle = sf::Shape::Circle(0, 0, 7, sf::Color::Blue);
-    /// \param outlineColor : Color used to draw the outline
+    /// \endcode
+    ///
+    /// \param x            X coordinate of the center
+    /// \param y            Y coordinate of the center
+    /// \param radius       Radius of the circle
+    /// \param color        Color of the shape's points
+    /// \param outline      Outline width
+    /// \param outlineColor Outline color of the shape's points
+    ///
+    /// \see Line, Rectangle
     ///
     ////////////////////////////////////////////////////////////
     static Shape Circle(float x, float y, float radius, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
 
     ////////////////////////////////////////////////////////////
-    /// Create a shape made of a single circle (use vectors)
+    /// \brief Create a new circular shape
     ///
-    /// \param center :       Position of the center
+    /// This is a static function that returns a new object,
-    /// \param radius :       Radius
+    /// don't try to call it on an existing object to modify it.
-    /// \param color :        Color used to fill the circle
+    /// \begincode
-    /// \param outline :      Outline width
+    /// sf::Vector2f center(0, 0);
-    /// \param outlineColor : Color used to draw the outline
+    /// sf::Shape circle = sf::Shape::Circle(center, 7, sf::Color::Blue);
+    /// \endcode
+    ///
+    /// \param center       Center of the circle
+    /// \param radius       Radius of the circle
+    /// \param color        Color of the shape's points
+    /// \param outline      Outline width
+    /// \param outlineColor Outline color of the shape's points
+    ///
+    /// \see Line, Rectangle
     ///
     ////////////////////////////////////////////////////////////
     static Shape Circle(const Vector2f& center, float radius, const Color& color, float outline = 0.f, const Color& outlineColor = Color(0, 0, 0));
@@ -255,7 +370,10 @@ public :
 protected :
 
     ////////////////////////////////////////////////////////////
-    /// /see Drawable::Render
+    /// \brief Draw the object to a render target
+    ///
+    /// \param target   Render target
+    /// \param renderer Renderer providing low-level rendering commands
     ///
     ////////////////////////////////////////////////////////////
     virtual void Render(RenderTarget& target, Renderer& renderer) const;
@@ -263,17 +381,20 @@ protected :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// Compile the shape : compute its center and its outline
+    /// \brief Compile the shape
+    ///
+    /// This function precomputes all the internal parameters
+    /// needed to properly render the shape (center, outline points).
     ///
     ////////////////////////////////////////////////////////////
     void Compile();
 
     ////////////////////////////////////////////////////////////
-    /// Compute the normal of a given 2D segment
+    /// \brief Compute the normal of a given 2D segment
     ///
-    /// \param p1 :     First point of the segment
+    /// \param p1     First point of the segment
-    /// \param p2 :     Second point of the segment
+    /// \param p2     Second point of the segment
-    /// \param normal : Calculated normal
+    /// \param normal Variable to fill with the calculated normal
     ///
     /// \return False if the normal couldn't be calculated (segment is null)
     ///
@@ -281,7 +402,8 @@ private :
     static bool ComputeNormal(const Vector2f& p1, const Vector2f& p2, Vector2f& normal);
 
     ////////////////////////////////////////////////////////////
-    /// Defines a simple 2D point
+    /// \brief Define a simple 2D point with position, normal and colors
+    ///
     ////////////////////////////////////////////////////////////
     struct Point
     {

include/SFML/Graphics/Sprite.hpp

@@ -38,116 +38,177 @@ namespace sf
 class Image;
 
 ////////////////////////////////////////////////////////////
-/// Sprite defines a sprite : texture, transformations,
+/// \brief Drawable representation of an image, with its
-/// color, and draw on screen
+///        own transformations, color, blend mode, etc.
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Sprite : public Drawable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
+    ///
+    /// Creates an empty sprite with no source image.
     ///
     ////////////////////////////////////////////////////////////
     Sprite();
 
     ////////////////////////////////////////////////////////////
-    /// Construct the sprite from a source image
+    /// \brief Construct the sprite from a source image
     ///
-    /// \param image :    Image of the sprite
+    /// \param image    Source image, that the sprite will display
-    /// \param position : Position of the sprite
+    /// \param position Position of the sprite in the scene
-    /// \param scale :    Scale factor
+    /// \param scale    Scale factor of the sprite
-    /// \param rotation : Orientation, in degrees
+    /// \param rotation Rotation angle, in degrees
-    /// \param color :    Color of the sprite
+    /// \param color    Global color of the sprite
+    ///
+    /// \see SetImage
     ///
     ////////////////////////////////////////////////////////////
     explicit Sprite(const Image& image, const Vector2f& position = Vector2f(0, 0), const Vector2f& scale = Vector2f(1, 1), float rotation = 0.f, const Color& color = Color(255, 255, 255, 255));
 
     ////////////////////////////////////////////////////////////
-    /// Change the image of the sprite
+    /// \brief Change the source image of the sprite
     ///
-    /// \param image :           New image
+    /// The \a image argument refers to an image that must
-    /// \param adjustToNewSize : If true, the SubRect of the sprite will be adjusted to the size of the new image
+    /// exist as long as the sprite uses it. Indeed, the sprite
+    /// doesn't store its own copy of the image, but rather keeps
+    /// a pointer to the one that you passed to this function.
+    /// If the source image is destroyed and the sprite tries to
+    /// use it, it may appear as a white rectangle.
+    /// If \a adjustToNewSize is true, the SubRect property of
+    /// the sprite is adjusted to the size of the new image. If
+    /// it is false, the SubRect is unchanged.
+    ///
+    /// \param image           New image
+    /// \param adjustToNewSize Should the sub-rect be adjusted to the size of the new image?
+    ///
+    /// \see GetImage, SetSubRect
     ///
     ////////////////////////////////////////////////////////////
     void SetImage(const Image& image, bool adjustToNewSize = false);
 
     ////////////////////////////////////////////////////////////
-    /// Set the sub-rectangle of the sprite inside the source image.
+    /// \brief Set the part of the image that the sprite will display
-    /// By default, the subrect covers the entire source image
     ///
-    /// \param rectangle : New sub-rectangle
+    /// The sub-rectangle is useful when you don't want to display
+    /// the whole image, but rather a part of it.
+    /// By default, the sub-rectangle covers the entire image.
+    ///
+    /// \param rectangle Rectangle defining the region of the image to display
+    ///
+    /// \see GetSubRect, SetImage
     ///
     ////////////////////////////////////////////////////////////
     void SetSubRect(const IntRect& rectangle);
 
     ////////////////////////////////////////////////////////////
-    /// Resize the sprite (by changing its scale factors) (take 2 values).
+    /// \brief Change the size of the sprite
-    /// The default size is defined by the subrect
     ///
-    /// \param width :  New width (must be strictly positive)
+    /// This function is just a shortcut that calls SetScale
-    /// \param height : New height (must be strictly positive)
+    /// with the proper values, calculated from the size of
+    /// the current subrect.
+    /// If \a width or \a height is not strictly positive,
+    /// this functions does nothing.
+    ///
+    /// \param width  New width of the sprite
+    /// \param height New height of the sprite
+    ///
+    /// \see GetSize
     ///
     ////////////////////////////////////////////////////////////
     void Resize(float width, float height);
 
     ////////////////////////////////////////////////////////////
-    /// Resize the sprite (by changing its scale factors) (take a 2D vector).
+    /// \brief Change the size of the sprite
-    /// The default size is defined by the subrect
     ///
-    /// \param size : New size (both coordinates must be strictly positive)
+    /// This function is just a shortcut that calls SetScale
+    /// with the proper values, calculated from the size of
+    /// the current subrect.
+    /// If \a size.x or \a size.y is not strictly positive,
+    /// this functions does nothing.
+    ///
+    /// \param size New size of the sprite
+    ///
+    /// \see GetSize
     ///
     ////////////////////////////////////////////////////////////
     void Resize(const Vector2f& size);
 
     ////////////////////////////////////////////////////////////
-    /// Flip the sprite horizontally
+    /// \brief Flip the sprite horizontally
     ///
-    /// \param flipped : True to flip the sprite
+    /// \param flipped True to flip the sprite
+    ///
+    /// \see FlipY
     ///
     ////////////////////////////////////////////////////////////
     void FlipX(bool flipped);
 
     ////////////////////////////////////////////////////////////
-    /// Flip the sprite vertically
+    /// \brief Flip the sprite vertically
     ///
-    /// \param flipped : True to flip the sprite
+    /// \param flipped True to flip the sprite
+    ///
+    /// \see FlipX
     ///
     ////////////////////////////////////////////////////////////
     void FlipY(bool flipped);
 
     ////////////////////////////////////////////////////////////
-    /// Get the source image of the sprite
+    /// \brief Get the source image of the sprite
     ///
-    /// \return Pointer to the image (can be NULL)
+    /// If the sprite has no source image, or if the image
+    /// doesn't exist anymore, a NULL pointer is returned.
+    /// The returned pointer is const, which means that you can't
+    /// modify the image when you retrieve it with this function.
+    ///
+    /// \return Pointer to the sprite's image
+    ///
+    /// \see SetImage
     ///
     ////////////////////////////////////////////////////////////
     const Image* GetImage() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the sub-rectangle of the sprite inside the source image
+    /// \brief Get the region of the image displayed by the sprite
     ///
-    /// \return Sub-rectangle
+    /// \return Rectangle defining the region of the image
+    ///
+    /// \see SetSubRect
     ///
     ////////////////////////////////////////////////////////////
     const IntRect& GetSubRect() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the sprite size
+    /// \brief Get the global size of the sprite
+    ///
+    /// This function is a shortcut that multiplies the
+    /// size of the subrect by the scale factors.
     ///
     /// \return Size of the sprite
     ///
+    /// \see Resize
+    ///
     ////////////////////////////////////////////////////////////
     Vector2f GetSize() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the color of a given pixel in the sprite
+    /// \brief Get the color of a given pixel in the sprite
-    /// (point is in local coordinates)
     ///
-    /// \param x : X coordinate of the pixel to get
+    /// This function returns the source image pixel, multiplied
-    /// \param y : Y coordinate of the pixel to get
+    /// by the global color of the sprite.
+    /// The input point must be in local coordinates. If you have
+    /// a global point, you can use the TransformToLocal function
+    /// to make it local.
+    /// This function doesn't perform any check, you must ensure that
+    /// the \a x and \a y coordinates are not out of bounds.
     ///
-    /// \return Color of pixel (x, y)
+    /// \param x X coordinate of the pixel to get
+    /// \param y Y coordinate of the pixel to get
+    ///
+    /// \return Color of the pixel
     ///
     ////////////////////////////////////////////////////////////
     Color GetPixel(unsigned int x, unsigned int y) const;
@@ -155,7 +216,10 @@ public :
 protected :
 
     ////////////////////////////////////////////////////////////
-    /// /see Drawable::Render
+    /// \brief Draw the object to a render target
+    ///
+    /// \param target   Render target
+    /// \param renderer Renderer providing low-level rendering commands
     ///
     ////////////////////////////////////////////////////////////
     virtual void Render(RenderTarget& target, Renderer& renderer) const;

include/SFML/Graphics/Text.hpp

@@ -39,121 +39,179 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Text defines a graphical 2D text, that can be drawn on screen
+/// \brief Graphical text that can be drawn to a render target
+///
 ////////////////////////////////////////////////////////////
 class SFML_API Text : public Drawable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Enumerate the string drawing styles
+    /// \brief Enumeration of the string drawing styles
+    ///
     ////////////////////////////////////////////////////////////
     enum Style
     {
         Regular    = 0,      ///< Regular characters, no style
-        Bold       = 1 << 0, ///< Characters are bold
+        Bold       = 1 << 0, ///< Bold characters
-        Italic     = 1 << 1, ///< Characters are in italic
+        Italic     = 1 << 1, ///< Italic characters
-        Underlined = 1 << 2  ///< Characters are underlined
+        Underlined = 1 << 2  ///< Underlined characters
     };
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
+    ///
+    /// Creates an empty text.
     ///
     ////////////////////////////////////////////////////////////
     Text();
 
     ////////////////////////////////////////////////////////////
-    /// Construct the string from any kind of text
+    /// \brief Construct the string from a string, font and size
     ///
-    /// \param string :        Text assigned to the string
+    /// \param string         Text assigned to the string
-    /// \param font :          Font used to draw the string
+    /// \param font           Font used to draw the string
-    /// \param characterSize : Base size of characters, in pixels
+    /// \param characterSize  Base size of characters, in pixels
     ///
     ////////////////////////////////////////////////////////////
     explicit Text(const String& string, const Font& font = Font::GetDefaultFont(), unsigned int characterSize = 30);
 
     ////////////////////////////////////////////////////////////
-    /// Set the text (from any kind of string)
+    /// \brief Set the text's string
     ///
-    /// \param string : New text
+    /// The \a string argument is a sf::String, which can
+    /// automatically be constructed from standard string types.
+    /// So, the following calls are all valid:
+    /// \begincode
+    /// text.SetString("hello");
+    /// text.SetString(L"hello");
+    /// text.SetString(std::string("hello"));
+    /// text.SetString(std::wstring(L"hello"));
+    /// \endcode
+    /// A text's string is empty by default.
+    ///
+    /// \param string New string
+    ///
+    /// \see GetString
     ///
     ////////////////////////////////////////////////////////////
     void SetString(const String& string);
 
     ////////////////////////////////////////////////////////////
-    /// Set the font of the string
+    /// \brief Set the text's font
     ///
-    /// \param font : Font to use
+    /// Texts have a valid font by default, which the built-in
+    /// Font::GetDefaultFont().
+    ///
+    /// \param font New font
+    ///
+    /// \see GetFont
     ///
     ////////////////////////////////////////////////////////////
     void SetFont(const Font& font);
 
     ////////////////////////////////////////////////////////////
-    /// Set the base size for the characters.
+    /// \brief Set the character size
-    /// The default size is 30
     ///
-    /// \param size : New size, in pixels
+    /// The default size is 30.
+    ///
+    /// \param size New character size, in pixels
+    ///
+    /// \see GetCharacterSize
     ///
     ////////////////////////////////////////////////////////////
     void SetCharacterSize(unsigned int size);
 
     ////////////////////////////////////////////////////////////
-    /// Set the style of the text
+    /// \brief Set the text's style
-    /// The default style is Regular
     ///
-    /// \param style : New text style (combination of Style enum values)
+    /// You can pass a combination of one or more styles, for
+    /// example sf::Text::Bold | sf::Text::Italic.
+    /// The default style is sf::Text::Regular.
+    ///
+    /// \param style New style
+    ///
+    /// \see GetStyle
     ///
     ////////////////////////////////////////////////////////////
     void SetStyle(unsigned long style);
 
     ////////////////////////////////////////////////////////////
-    /// Get the text (the returned text can be converted implicitely to any kind of string)
+    /// \brief Get the text's string
     ///
-    /// \return String's text
+    /// The returned string is a sf::String, which can automatically
+    /// be converted to standard string types. So, the following
+    /// lines of code are all valid:
+    /// \begincode
+    /// sf::String   s1 = text.GetString();
+    /// std::string  s2 = text.GetString();
+    /// std::wstring s3 = text.GetString();
+    /// \endcode
+    ///
+    /// \return Text's string
+    ///
+    /// \see GetString
     ///
     ////////////////////////////////////////////////////////////
     const String& GetString() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the font used by the string
+    /// \brief Get the text's font
     ///
-    /// \return Font used
+    /// The returned reference is const, which means that you
+    /// cannot modify the font when you get it from this function.
+    ///
+    /// \return Text's font
+    ///
+    /// \see SetFont
     ///
     ////////////////////////////////////////////////////////////
     const Font& GetFont() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the base size of characters
+    /// \brief Get the character size
     ///
     /// \return Size of the characters, in pixels
     ///
+    /// \see SetCharacterSize
+    ///
     ////////////////////////////////////////////////////////////
     unsigned int GetCharacterSize() const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the style of the text
+    /// \brief Get the text's style
     ///
-    /// \return Current string style (combination of Style enum values)
+    /// \return Text's style
+    ///
+    /// \see SetStyle
     ///
     ////////////////////////////////////////////////////////////
     unsigned long GetStyle() const;
 
     ////////////////////////////////////////////////////////////
-    /// Return the visual position of the Index-th character of the string,
+    /// \brief Return the position of the \a index-th character
-    /// in coordinates relative to the string
-    /// (note : translation, center, rotation and scale are not applied)
     ///
-    /// \param index : Index of the character
+    /// This function computes the visual position of a character
+    /// from its index in the string. The returned position is
+    /// in local coordinates (translation, rotation, scale and
+    /// origin are not applied). You can easily get the corresponding
+    /// global position with the TransformToGlobal function.
+    /// If \a index is out of range, the position of the end of
+    /// the string is returned.
     ///
-    /// \return Position of the index-th character (end of string if Index is out of range)
+    /// \param index Index of the character
+    ///
+    /// \return Position of the character
     ///
     ////////////////////////////////////////////////////////////
     Vector2f GetCharacterPos(std::size_t index) const;
 
     ////////////////////////////////////////////////////////////
-    /// Get the string rectangle on screen
+    /// \brief Get the bounding rectangle of the text
     ///
-    /// \return Rectangle contaning the string in screen coordinates
+    /// The returned rectangle is in global coordinates.
+    ///
+    /// \return Bounding rectangle of the text
     ///
     ////////////////////////////////////////////////////////////
     FloatRect GetRect() const;
@@ -161,7 +219,10 @@ public :
 protected :
 
     ////////////////////////////////////////////////////////////
-    /// /see Drawable::Render
+    /// \brief Draw the object to a render target
+    ///
+    /// \param target   Render target
+    /// \param renderer Renderer providing low-level rendering commands
     ///
     ////////////////////////////////////////////////////////////
     virtual void Render(RenderTarget& target, Renderer& renderer) const;
@@ -169,7 +230,7 @@ protected :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// Recompute the bounding rectangle of the text
+    /// \brief Recompute the bounding rectangle
     ///
     ////////////////////////////////////////////////////////////
     void UpdateRect() const;

samples/win32/Win32.cpp

@@ -82,6 +82,7 @@ INT WINAPI WinMain(HINSTANCE instance, HINSTANCE, LPSTR, INT)
     sf::Sprite sprite1(image1);
     sf::Sprite sprite2(image2);
     sprite1.SetOrigin(sprite1.GetSize() / 2.f);
+    sprite1.SetPosition(sprite1.GetSize() / 2.f);
 
     // Create a clock for measuring elapsed time
     sf::Clock clock;

src/SFML/Graphics/GLCheck.cpp

@@ -34,8 +34,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Check the last OpenGL error
-////////////////////////////////////////////////////////////
 void GLCheckError(const std::string& file, unsigned int line)
 {
     // Get the last error
@@ -108,8 +106,6 @@ void GLCheckError(const std::string& file, unsigned int line)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Make sure that GLEW is initialized
 ////////////////////////////////////////////////////////////
 void EnsureGlewInit()
 {

src/SFML/Graphics/GLCheck.hpp

@@ -54,16 +54,16 @@ namespace priv
 #endif
 
 ////////////////////////////////////////////////////////////
-/// Check the last OpenGL error
+/// \brief Check the last OpenGL error
 ///
-/// \param file : Source file where the call is located
+/// \param file Source file where the call is located
-/// \param line : Line number of the source file where the call is located
+/// \param line Line number of the source file where the call is located
 ///
 ////////////////////////////////////////////////////////////
 void GLCheckError(const std::string& file, unsigned int line);
 
 ////////////////////////////////////////////////////////////
-/// Make sure that GLEW is initialized
+/// \brief Make sure that GLEW is initialized
 ///
 ////////////////////////////////////////////////////////////
 void EnsureGlewInit();

src/SFML/Graphics/Image.cpp

@@ -39,8 +39,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 Image::Image() :
 myWidth         (0),
 myHeight        (0),
@@ -56,8 +54,6 @@ myPixelsFlipped (false)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy constructor
 ////////////////////////////////////////////////////////////
 Image::Image(const Image& copy) :
 Resource<Image>()
@@ -82,8 +78,6 @@ Resource<Image>()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 Image::~Image()
 {
@@ -92,8 +86,6 @@ Image::~Image()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Load the image from a file
 ////////////////////////////////////////////////////////////
 bool Image::LoadFromFile(const std::string& filename)
 {
@@ -115,19 +107,17 @@ bool Image::LoadFromFile(const std::string& filename)
 
 
 ////////////////////////////////////////////////////////////
-/// Load the image from a file in memory
+bool Image::LoadFromMemory(const void* data, std::size_t size)
-////////////////////////////////////////////////////////////
-bool Image::LoadFromMemory(const void* data, std::size_t sizeInBytes)
 {
     // Check parameters
-    if (!data || (sizeInBytes == 0))
+    if (!data || (size == 0))
     {
         Err() << "Failed to image font from memory, no data provided" << std::endl;
         return false;
     }
 
     // Let the image loader load the image into our pixel array
-    bool success = priv::ImageLoader::GetInstance().LoadImageFromMemory(data, sizeInBytes, myPixels, myWidth, myHeight);
+    bool success = priv::ImageLoader::GetInstance().LoadImageFromMemory(data, size, myPixels, myWidth, myHeight);
 
     if (success)
     {
@@ -143,8 +133,6 @@ bool Image::LoadFromMemory(const void* data, std::size_t sizeInBytes)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Load the image directly from an array of pixels
 ////////////////////////////////////////////////////////////
 bool Image::LoadFromPixels(unsigned int width, unsigned int height, const Uint8* data)
 {
@@ -178,8 +166,6 @@ bool Image::LoadFromPixels(unsigned int width, unsigned int height, const Uint8*
 }
 
 
-////////////////////////////////////////////////////////////
-/// Save the content of the image to a file
 ////////////////////////////////////////////////////////////
 bool Image::SaveToFile(const std::string& filename) const
 {
@@ -191,8 +177,6 @@ bool Image::SaveToFile(const std::string& filename) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create an empty image
 ////////////////////////////////////////////////////////////
 bool Image::Create(unsigned int width, unsigned int height, const Color& color)
 {
@@ -228,8 +212,6 @@ bool Image::Create(unsigned int width, unsigned int height, const Color& color)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create transparency mask from a specified colorkey
 ////////////////////////////////////////////////////////////
 void Image::CreateMaskFromColor(const Color& color, Uint8 alpha)
 {
@@ -255,10 +237,6 @@ void Image::CreateMaskFromColor(const Color& color, Uint8 alpha)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Copy pixels from another image onto this one.
-/// This function does a slow pixel copy and should only
-/// be used at initialization time
 ////////////////////////////////////////////////////////////
 void Image::Copy(const Image& source, unsigned int destX, unsigned int destY, const IntRect& sourceRect, bool applyAlpha)
 {
@@ -345,9 +323,6 @@ void Image::Copy(const Image& source, unsigned int destX, unsigned int destY, co
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create the image from the current contents of the
-/// given window
 ////////////////////////////////////////////////////////////
 bool Image::CopyScreen(RenderWindow& window, const IntRect& sourceRect)
 {
@@ -397,8 +372,6 @@ bool Image::CopyScreen(RenderWindow& window, const IntRect& sourceRect)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the color of a pixel
 ////////////////////////////////////////////////////////////
 void Image::SetPixel(unsigned int x, unsigned int y, const Color& color)
 {
@@ -417,8 +390,6 @@ void Image::SetPixel(unsigned int x, unsigned int y, const Color& color)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get a pixel from the image
 ////////////////////////////////////////////////////////////
 Color Image::GetPixel(unsigned int x, unsigned int y) const
 {
@@ -432,10 +403,6 @@ Color Image::GetPixel(unsigned int x, unsigned int y) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get a read-only pointer to the array of pixels (RGBA 8 bits integers components)
-/// Array size is GetWidth() x GetHeight() x 4
-/// This pointer becomes invalid if you reload or resize the image
 ////////////////////////////////////////////////////////////
 const Uint8* Image::GetPixelsPtr() const
 {
@@ -454,8 +421,6 @@ const Uint8* Image::GetPixelsPtr() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Update the whole image from an array of pixels
 ////////////////////////////////////////////////////////////
 void Image::UpdatePixels(const Uint8* pixels)
 {
@@ -473,8 +438,6 @@ void Image::UpdatePixels(const Uint8* pixels)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Update a sub-rectangle of the image from an array of pixels
 ////////////////////////////////////////////////////////////
 void Image::UpdatePixels(const Uint8* pixels, const IntRect& rectangle)
 {
@@ -495,8 +458,6 @@ void Image::UpdatePixels(const Uint8* pixels, const IntRect& rectangle)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Bind the image for rendering
 ////////////////////////////////////////////////////////////
 void Image::Bind() const
 {
@@ -508,8 +469,6 @@ void Image::Bind() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Enable or disable image smoothing filter
 ////////////////////////////////////////////////////////////
 void Image::SetSmooth(bool smooth)
 {
@@ -532,8 +491,6 @@ void Image::SetSmooth(bool smooth)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the width of the image
 ////////////////////////////////////////////////////////////
 unsigned int Image::GetWidth() const
 {
@@ -541,8 +498,6 @@ unsigned int Image::GetWidth() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the height of the image
 ////////////////////////////////////////////////////////////
 unsigned int Image::GetHeight() const
 {
@@ -550,8 +505,6 @@ unsigned int Image::GetHeight() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Tells whether the smooth filtering is enabled or not
 ////////////////////////////////////////////////////////////
 bool Image::IsSmooth() const
 {
@@ -559,9 +512,6 @@ bool Image::IsSmooth() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Convert a subrect expressed in pixels, into float
-/// texture coordinates
 ////////////////////////////////////////////////////////////
 FloatRect Image::GetTexCoords(const IntRect& rect) const
 {
@@ -592,8 +542,6 @@ FloatRect Image::GetTexCoords(const IntRect& rect) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the maximum image size according to hardware support
 ////////////////////////////////////////////////////////////
 unsigned int Image::GetMaximumSize()
 {
@@ -605,7 +553,25 @@ unsigned int Image::GetMaximumSize()
 
 
 ////////////////////////////////////////////////////////////
-/// Get a valid image size according to hardware support
+Image& Image::operator =(const Image& other)
+{
+    Image temp(other);
+
+    std::swap(myWidth,          temp.myWidth);
+    std::swap(myHeight,         temp.myHeight);
+    std::swap(myTextureWidth,   temp.myTextureWidth);
+    std::swap(myTextureHeight,  temp.myTextureHeight);
+    std::swap(myTexture,        temp.myTexture);
+    std::swap(myIsSmooth,       temp.myIsSmooth);
+    std::swap(myArrayUpdated,   temp.myArrayUpdated);
+    std::swap(myTextureUpdated, temp.myTextureUpdated);
+    std::swap(myPixelsFlipped,  temp.myPixelsFlipped);
+    std::swap(myPixels,         temp.myPixels);
+
+    return *this;
+}
+
+
 ////////////////////////////////////////////////////////////
 unsigned int Image::GetValidSize(unsigned int size)
 {
@@ -629,30 +595,6 @@ unsigned int Image::GetValidSize(unsigned int size)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Assignment operator
-////////////////////////////////////////////////////////////
-Image& Image::operator =(const Image& other)
-{
-    Image temp(other);
-
-    std::swap(myWidth,          temp.myWidth);
-    std::swap(myHeight,         temp.myHeight);
-    std::swap(myTextureWidth,   temp.myTextureWidth);
-    std::swap(myTextureHeight,  temp.myTextureHeight);
-    std::swap(myTexture,        temp.myTexture);
-    std::swap(myIsSmooth,       temp.myIsSmooth);
-    std::swap(myArrayUpdated,   temp.myArrayUpdated);
-    std::swap(myTextureUpdated, temp.myTextureUpdated);
-    std::swap(myPixelsFlipped,  temp.myPixelsFlipped);
-    std::swap(myPixels,         temp.myPixels);
-
-    return *this;
-}
-
-
-////////////////////////////////////////////////////////////
-/// Create the OpenGL texture
 ////////////////////////////////////////////////////////////
 bool Image::CreateTexture()
 {
@@ -688,8 +630,8 @@ bool Image::CreateTexture()
     GLCheck(glGetIntegerv(GL_TEXTURE_BINDING_2D, &previous));
     GLCheck(glBindTexture(GL_TEXTURE_2D, myTexture));
     GLCheck(glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, myTextureWidth, myTextureHeight, 0, GL_RGBA, GL_UNSIGNED_BYTE, NULL));
-    GLCheck(glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP));
+    GLCheck(glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE));
-    GLCheck(glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP));
+    GLCheck(glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE));
     GLCheck(glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, myIsSmooth ? GL_LINEAR : GL_NEAREST));
     GLCheck(glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, myIsSmooth ? GL_LINEAR : GL_NEAREST));
     GLCheck(glBindTexture(GL_TEXTURE_2D, previous));
@@ -700,9 +642,6 @@ bool Image::CreateTexture()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Make sure the texture in video memory is updated with the
-/// array of pixels
 ////////////////////////////////////////////////////////////
 void Image::EnsureTextureUpdate() const
 {
@@ -726,9 +665,6 @@ void Image::EnsureTextureUpdate() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Make sure the array of pixels is updated with the
-/// texture in video memory
 ////////////////////////////////////////////////////////////
 void Image::EnsureArrayUpdate() const
 {
@@ -787,8 +723,6 @@ void Image::EnsureArrayUpdate() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Make sure that the image is ready to be used
 ////////////////////////////////////////////////////////////
 void Image::Use() const
 {
@@ -796,8 +730,6 @@ void Image::Use() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Reset the image attributes
 ////////////////////////////////////////////////////////////
 void Image::Reset()
 {
@@ -816,8 +748,6 @@ void Image::Reset()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destroy the OpenGL texture
 ////////////////////////////////////////////////////////////
 void Image::DestroyTexture()
 {

src/SFML/Graphics/ImageLoader.cpp

@@ -42,8 +42,6 @@ extern "C"
 
 namespace
 {
-    ////////////////////////////////////////////////////////////
-    /// Error callback for PNG writing
     ////////////////////////////////////////////////////////////
     void PngErrorHandler(png_structp png, png_const_charp message)
     {
@@ -58,8 +56,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Get the unique instance of the class
-////////////////////////////////////////////////////////////
 ImageLoader& ImageLoader::GetInstance()
 {
     static ImageLoader Instance;
@@ -68,8 +64,6 @@ ImageLoader& ImageLoader::GetInstance()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Default constructor
 ////////////////////////////////////////////////////////////
 ImageLoader::ImageLoader()
 {
@@ -77,8 +71,6 @@ ImageLoader::ImageLoader()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 ImageLoader::~ImageLoader()
 {
@@ -86,8 +78,6 @@ ImageLoader::~ImageLoader()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Load pixels from an image file
 ////////////////////////////////////////////////////////////
 bool ImageLoader::LoadImageFromFile(const std::string& filename, std::vector<Uint8>& pixels, unsigned int& width, unsigned int& height)
 {
@@ -124,18 +114,15 @@ bool ImageLoader::LoadImageFromFile(const std::string& filename, std::vector<Uin
 
 
 ////////////////////////////////////////////////////////////
-/// Load pixels from an image file in memory
+bool ImageLoader::LoadImageFromMemory(const void* data, std::size_t size, std::vector<Uint8>& pixels, unsigned int& width, unsigned int& height)
-////////////////////////////////////////////////////////////
-bool ImageLoader::LoadImageFromMemory(const void* data, std::size_t sizeInBytes, std::vector<Uint8>& pixels, unsigned int& width, unsigned int& height)
 {
     // Clear the array (just in case)
     pixels.clear();
 
     // Load the image and get a pointer to the pixels in memory
-    const unsigned char* buffer = static_cast<const unsigned char*>(data);
-    int size = static_cast<int>(sizeInBytes);
     int imgWidth, imgHeight, imgChannels;
-    unsigned char* ptr = SOIL_load_image_from_memory(buffer, size, &imgWidth, &imgHeight, &imgChannels, SOIL_LOAD_RGBA);
+    const unsigned char* buffer = static_cast<const unsigned char*>(data);
+    unsigned char* ptr = SOIL_load_image_from_memory(buffer, static_cast<int>(size), &imgWidth, &imgHeight, &imgChannels, SOIL_LOAD_RGBA);
 
     if (ptr)
     {
@@ -162,8 +149,6 @@ bool ImageLoader::LoadImageFromMemory(const void* data, std::size_t sizeInBytes,
 }
 
 
-////////////////////////////////////////////////////////////
-/// Save pixels to an image file
 ////////////////////////////////////////////////////////////
 bool ImageLoader::SaveImageToFile(const std::string& filename, const std::vector<Uint8>& pixels, unsigned int width, unsigned int height)
 {
@@ -200,8 +185,6 @@ bool ImageLoader::SaveImageToFile(const std::string& filename, const std::vector
 }
 
 
-////////////////////////////////////////////////////////////
-/// Save a JPG image file
 ////////////////////////////////////////////////////////////
 bool ImageLoader::WriteJpg(const std::string& filename, const std::vector<Uint8>& pixels, unsigned int width, unsigned int height)
 {
@@ -259,8 +242,6 @@ bool ImageLoader::WriteJpg(const std::string& filename, const std::vector<Uint8>
 }
 
 
-////////////////////////////////////////////////////////////
-/// Save a PNG image file
 ////////////////////////////////////////////////////////////
 bool ImageLoader::WritePng(const std::string& filename, const std::vector<Uint8>& pixels, unsigned int width, unsigned int height)
 {

src/SFML/Graphics/ImageLoader.hpp

@@ -38,15 +38,15 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// ImageLoader load and save images from files ;
+/// \brief Load/save image files
-/// Supported formats are : bmp, dds, jpg, png, tga, psd
+///
 ////////////////////////////////////////////////////////////
 class ImageLoader : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Get the unique instance of the class
+    /// \brief Get the unique instance of the class
     ///
     /// \return Reference to the ImageLoader instance
     ///
@@ -54,12 +54,12 @@ public :
     static ImageLoader& GetInstance();
 
     ////////////////////////////////////////////////////////////
-    /// Load pixels from an image file
+    /// \brief Load an image from a file on disk
     ///
-    /// \param filename : Path of image file to load
+    /// \param filename Path of image file to load
-    /// \param pixels :   Array of pixels to fill with loaded image
+    /// \param pixels   Array of pixels to fill with loaded image
-    /// \param width :    Width of loaded image, in pixels
+    /// \param width    Width of loaded image, in pixels
-    /// \param height :   Height of loaded image, in pixels
+    /// \param height   Height of loaded image, in pixels
     ///
     /// \return True if loading was successful
     ///
@@ -67,26 +67,26 @@ public :
     bool LoadImageFromFile(const std::string& filename, std::vector<Uint8>& pixels, unsigned int& width, unsigned int& height);
 
     ////////////////////////////////////////////////////////////
-    /// Load pixels from an image file in memory
+    /// \brief Load an image from a file inn memory
     ///
-    /// \param data :        Pointer to the file data in memory
+    /// \param data   Pointer to the file data in memory
-    /// \param sizeInBytes : Size of the data to load, in bytes
+    /// \param size   Size of the data to load, in bytes
-    /// \param pixels :      Array of pixels to fill with loaded image
+    /// \param pixels Array of pixels to fill with loaded image
-    /// \param width :       Width of loaded image, in pixels
+    /// \param width  Width of loaded image, in pixels
-    /// \param height :      Height of loaded image, in pixels
+    /// \param height Height of loaded image, in pixels
     ///
     /// \return True if loading was successful
     ///
     ////////////////////////////////////////////////////////////
-    bool LoadImageFromMemory(const void* data, std::size_t sizeInBytes, std::vector<Uint8>& pixels, unsigned int& width, unsigned int& height);
+    bool LoadImageFromMemory(const void* data, std::size_t size, std::vector<Uint8>& pixels, unsigned int& width, unsigned int& height);
 
     ////////////////////////////////////////////////////////////
-    /// Save pixels to an image file
+    /// \bref Save an array of pixels as an image file
     ///
-    /// \param filename : Path of image file to save
+    /// \param filename Path of image file to save
-    /// \param pixels :   Array of pixels to save to image
+    /// \param pixels   Array of pixels to save to image
-    /// \param width :    Width of image to save, in pixels
+    /// \param width    Width of image to save, in pixels
-    /// \param height :   Height of image to save, in pixels
+    /// \param height   Height of image to save, in pixels
     ///
     /// \return True if saving was successful
     ///
@@ -96,24 +96,24 @@ public :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     ImageLoader();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~ImageLoader();
 
     ////////////////////////////////////////////////////////////
-    /// Save a JPG image file
+    /// \brief Save an image file in JPEG format
     ///
-    /// \param filename : Path of image file to save
+    /// \param filename Path of image file to save
-    /// \param pixels :   Array of pixels to save to image
+    /// \param pixels   Array of pixels to save to image
-    /// \param width :    Width of image to save, in pixels
+    /// \param width    Width of image to save, in pixels
-    /// \param height :   Height of image to save, in pixels
+    /// \param height   Height of image to save, in pixels
     ///
     /// \return True if saving was successful
     ///
@@ -121,12 +121,12 @@ private :
     bool WriteJpg(const std::string& filename, const std::vector<Uint8>& pixels, unsigned int width, unsigned int height);
 
     ////////////////////////////////////////////////////////////
-    /// Save a PNG image file
+    /// \brief Save an image file in PNG format
     ///
-    /// \param filename : Path of image file to save
+    /// \param filename Path of image file to save
-    /// \param pixels :   Array of pixels to save to image
+    /// \param pixels   Array of pixels to save to image
-    /// \param width :    Width of image to save, in pixels
+    /// \param width    Width of image to save, in pixels
-    /// \param height :   Height of image to save, in pixels
+    /// \param height   Height of image to save, in pixels
     ///
     /// \return True if saving was successful
     ///

src/SFML/Graphics/Linux/RenderImageImplPBuffer.cpp

@@ -36,8 +36,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 RenderImageImplPBuffer::RenderImageImplPBuffer() :
 myPBuffer(NULL),
 myContext(NULL),
@@ -48,8 +46,6 @@ myHeight (0)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 RenderImageImplPBuffer::~RenderImageImplPBuffer()
 {
@@ -67,8 +63,6 @@ RenderImageImplPBuffer::~RenderImageImplPBuffer()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Check whether the system supports P-Buffer or not
 ////////////////////////////////////////////////////////////
 bool RenderImageImplPBuffer::IsSupported()
 {
@@ -79,8 +73,6 @@ bool RenderImageImplPBuffer::IsSupported()
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::Create
 ////////////////////////////////////////////////////////////
 bool RenderImageImplPBuffer::Create(unsigned int width, unsigned int height, unsigned int, bool depthBuffer)
 {
@@ -168,8 +160,6 @@ bool RenderImageImplPBuffer::Create(unsigned int width, unsigned int height, uns
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::Activate
 ////////////////////////////////////////////////////////////
 bool RenderImageImplPBuffer::Activate(bool active)
 {
@@ -197,8 +187,6 @@ bool RenderImageImplPBuffer::Activate(bool active)
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::UpdateTexture
 ////////////////////////////////////////////////////////////
 void RenderImageImplPBuffer::UpdateTexture(unsigned int textureId)
 {

src/SFML/Graphics/Linux/RenderImageImplPBuffer.hpp

@@ -39,26 +39,27 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Specialization of RenderImageImpl using GLX P-Buffers
+/// \brief Specialization of RenderImageImpl using GLX P-Buffers
+///
 ////////////////////////////////////////////////////////////
 class RenderImageImplPBuffer : public RenderImageImpl
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     RenderImageImplPBuffer();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~RenderImageImplPBuffer();
 
     ////////////////////////////////////////////////////////////
-    /// Check whether the system supports P-Buffer or not
+    /// \brief Check whether the system supports P-Buffer or not
     ///
     /// \return True if P-Buffer render images are supported
     ///
@@ -68,19 +69,32 @@ public :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::Create
+    /// \brief Create the render image implementation
+    ///
+    /// \param width       Width of the image to render to
+    /// \param height      Height of the image to render to
+    /// \param textureId   OpenGL texture identifier of the target image
+    /// \param depthBuffer Is a depth buffer requested?
+    ///
+    /// \return True if creation has been successful
     ///
     ////////////////////////////////////////////////////////////
     virtual bool Create(unsigned int width, unsigned int height, unsigned int textureId, bool depthBuffer);
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::Activate
+    /// \brief Activate or deactivate the render image for rendering
+    ///
+    /// \param active True to activate, false to deactivate
+    ///
+    /// \return True on success, false on failure
     ///
     ////////////////////////////////////////////////////////////
     virtual bool Activate(bool active);
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::UpdateTexture
+    /// \brief Update the pixels of the target texture
+    ///
+    /// \param textureId OpenGL identifier of the target texture
     ///
     ////////////////////////////////////////////////////////////
     virtual void UpdateTexture(unsigned textureId);

src/SFML/Graphics/RenderImageImpl.cpp

@@ -33,11 +33,9 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Destructor
-////////////////////////////////////////////////////////////
 RenderImageImpl::~RenderImageImpl()
 {
-
+    // Nothing to do
 }
 
 } // namespace priv

src/SFML/Graphics/RenderImageImpl.hpp

@@ -36,25 +36,26 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Abstract base class for render-image implementations
+/// \brief Abstract base class for render-image implementations
+///
 ////////////////////////////////////////////////////////////
 class RenderImageImpl : NonCopyable
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     virtual ~RenderImageImpl();
 
     ////////////////////////////////////////////////////////////
-    /// Create the render image
+    /// \brief Create the render image implementation
     ///
-    /// \param width :       Width of the image to render to
+    /// \param width       Width of the image to render to
-    /// \param height :      Height of the image to render to
+    /// \param height      Height of the image to render to
-    /// \param textureId :   OpenGL texture identifier of the target image
+    /// \param textureId   OpenGL texture identifier of the target image
-    /// \param depthBuffer : Do you want a depth buffer attached ?
+    /// \param depthBuffer Is a depth buffer requested?
     ///
     /// \return True if creation has been successful
     ///
@@ -62,17 +63,19 @@ public :
     virtual bool Create(unsigned int width, unsigned int height, unsigned int textureId, bool depthBuffer) = 0;
 
     ////////////////////////////////////////////////////////////
-    /// Activate / deactivate the render image for rendering
+    /// \brief Activate or deactivate the render image for rendering
     ///
-    /// \param active : True to activate, false to deactivate
+    /// \param active True to activate, false to deactivate
+    ///
+    /// \return True on success, false on failure
     ///
     ////////////////////////////////////////////////////////////
     virtual bool Activate(bool active) = 0;
 
     ////////////////////////////////////////////////////////////
-    /// Update the pixels of the target texture
+    /// \brief Update the pixels of the target texture
     ///
-    /// \param textureId : OpenGL identifier of the target texture
+    /// \param textureId OpenGL identifier of the target texture
     ///
     ////////////////////////////////////////////////////////////
     virtual void UpdateTexture(unsigned int textureId) = 0;

src/SFML/Graphics/RenderImageImplFBO.cpp

@@ -36,8 +36,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 RenderImageImplFBO::RenderImageImplFBO() :
 myFrameBuffer(0),
 myDepthBuffer(0)
@@ -46,8 +44,6 @@ myDepthBuffer(0)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 RenderImageImplFBO::~RenderImageImplFBO()
 {
@@ -67,8 +63,6 @@ RenderImageImplFBO::~RenderImageImplFBO()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Check whether the system supports FBOs or not
 ////////////////////////////////////////////////////////////
 bool RenderImageImplFBO::IsSupported()
 {
@@ -79,8 +73,6 @@ bool RenderImageImplFBO::IsSupported()
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::Create
 ////////////////////////////////////////////////////////////
 bool RenderImageImplFBO::Create(unsigned int width, unsigned int height, unsigned int textureId, bool depthBuffer)
 {
@@ -126,8 +118,6 @@ bool RenderImageImplFBO::Create(unsigned int width, unsigned int height, unsigne
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::Activate
 ////////////////////////////////////////////////////////////
 bool RenderImageImplFBO::Activate(bool active)
 {
@@ -136,12 +126,10 @@ bool RenderImageImplFBO::Activate(bool active)
     return true;
 }
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::UpdateTexture
 ////////////////////////////////////////////////////////////
 void RenderImageImplFBO::UpdateTexture(unsigned int)
 {
-    // Nothing to do: the FBO draws directly into the target image
+    // Nothing to do: the FBO draws directly to the target image
 }
 
 } // namespace priv

src/SFML/Graphics/RenderImageImplFBO.hpp

@@ -37,27 +37,28 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Specialization of RenderImageImpl using the
+/// \brief Specialization of RenderImageImpl using the
-/// Frame Buffer Object extension
+///        Frame Buffer Object OpenGL extension
+///
 ////////////////////////////////////////////////////////////
 class RenderImageImplFBO : public RenderImageImpl
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     RenderImageImplFBO();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~RenderImageImplFBO();
 
     ////////////////////////////////////////////////////////////
-    /// Check whether the system supports FBOs or not
+    /// \brief Check whether the system supports FBOs or not
     ///
     /// \return True if FBO render images are supported
     ///
@@ -67,19 +68,32 @@ public :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::Create
+    /// \brief Create the render image implementation
+    ///
+    /// \param width       Width of the image to render to
+    /// \param height      Height of the image to render to
+    /// \param textureId   OpenGL texture identifier of the target image
+    /// \param depthBuffer Is a depth buffer requested?
+    ///
+    /// \return True if creation has been successful
     ///
     ////////////////////////////////////////////////////////////
     virtual bool Create(unsigned int width, unsigned int height, unsigned int textureId, bool depthBuffer);
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::Activate
+    /// \brief Activate or deactivate the render image for rendering
+    ///
+    /// \param active True to activate, false to deactivate
+    ///
+    /// \return True on success, false on failure
     ///
     ////////////////////////////////////////////////////////////
     virtual bool Activate(bool active);
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::UpdateTexture
+    /// \brief Update the pixels of the target texture
+    ///
+    /// \param textureId OpenGL identifier of the target texture
     ///
     ////////////////////////////////////////////////////////////
     virtual void UpdateTexture(unsigned textureId);

src/SFML/Graphics/Shape.cpp

@@ -33,8 +33,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 Shape::Shape() :
 myOutline         (0.f),
 myIsFillEnabled   (true),
@@ -46,8 +44,6 @@ myIsCompiled      (false)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Add a point to the shape
 ////////////////////////////////////////////////////////////
 void Shape::AddPoint(float x, float y, const Color& color, const Color& outlineColor)
 {
@@ -55,8 +51,6 @@ void Shape::AddPoint(float x, float y, const Color& color, const Color& outlineC
 }
 
 
-////////////////////////////////////////////////////////////
-/// Add a point to the shape
 ////////////////////////////////////////////////////////////
 void Shape::AddPoint(const Vector2f& position, const Color& color, const Color& outlineColor)
 {
@@ -65,8 +59,6 @@ void Shape::AddPoint(const Vector2f& position, const Color& color, const Color&
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the number of points composing the shape
 ////////////////////////////////////////////////////////////
 unsigned int Shape::GetPointsCount() const
 {
@@ -74,9 +66,6 @@ unsigned int Shape::GetPointsCount() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Enable or disable filling the shape.
-/// Fill is enabled by default
 ////////////////////////////////////////////////////////////
 void Shape::EnableFill(bool enable)
 {
@@ -84,9 +73,6 @@ void Shape::EnableFill(bool enable)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Enable or disable drawing the shape outline.
-/// Outline is enabled by default
 ////////////////////////////////////////////////////////////
 void Shape::EnableOutline(bool enable)
 {
@@ -94,8 +80,6 @@ void Shape::EnableOutline(bool enable)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the position of a point
 ////////////////////////////////////////////////////////////
 void Shape::SetPointPosition(unsigned int index, const Vector2f& position)
 {
@@ -104,8 +88,6 @@ void Shape::SetPointPosition(unsigned int index, const Vector2f& position)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the position of a point
 ////////////////////////////////////////////////////////////
 void Shape::SetPointPosition(unsigned int index, float x, float y)
 {
@@ -113,8 +95,6 @@ void Shape::SetPointPosition(unsigned int index, float x, float y)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the color of a point
 ////////////////////////////////////////////////////////////
 void Shape::SetPointColor(unsigned int index, const Color& color)
 {
@@ -124,17 +104,13 @@ void Shape::SetPointColor(unsigned int index, const Color& color)
 
 
 ////////////////////////////////////////////////////////////
-/// Set the outline color of a point
+void Shape::SetPointOutlineColor(unsigned int index, const Color& color)
-////////////////////////////////////////////////////////////
-void Shape::SetPointOutlineColor(unsigned int index, const Color& outlineColor)
 {
-    myPoints[index + 1].OutlineCol = outlineColor;
+    myPoints[index + 1].OutlineCol = color;
     myIsCompiled = false;
 }
 
 
-////////////////////////////////////////////////////////////
-/// Change the width of the shape outline
 ////////////////////////////////////////////////////////////
 void Shape::SetOutlineWidth(float width)
 {
@@ -142,8 +118,6 @@ void Shape::SetOutlineWidth(float width)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the position of a point
 ////////////////////////////////////////////////////////////
 const Vector2f& Shape::GetPointPosition(unsigned int index) const
 {
@@ -151,8 +125,6 @@ const Vector2f& Shape::GetPointPosition(unsigned int index) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the color of a point
 ////////////////////////////////////////////////////////////
 const Color& Shape::GetPointColor(unsigned int index) const
 {
@@ -160,8 +132,6 @@ const Color& Shape::GetPointColor(unsigned int index) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the outline color of a point
 ////////////////////////////////////////////////////////////
 const Color& Shape::GetPointOutlineColor(unsigned int index) const
 {
@@ -169,8 +139,6 @@ const Color& Shape::GetPointOutlineColor(unsigned int index) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the width of the shape outline
 ////////////////////////////////////////////////////////////
 float Shape::GetOutlineWidth() const
 {
@@ -178,8 +146,6 @@ float Shape::GetOutlineWidth() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a shape made of a single line
 ////////////////////////////////////////////////////////////
 Shape Shape::Line(float p1x, float p1y, float p2x, float p2y, float thickness, const Color& color, float outline, const Color& outlineColor)
 {
@@ -190,8 +156,6 @@ Shape Shape::Line(float p1x, float p1y, float p2x, float p2y, float thickness, c
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a shape made of a single line (use vectors)
 ////////////////////////////////////////////////////////////
 Shape Shape::Line(const Vector2f& p1, const Vector2f& p2, float thickness, const Color& color, float outline, const Color& outlineColor)
 {
@@ -215,8 +179,6 @@ Shape Shape::Line(const Vector2f& p1, const Vector2f& p2, float thickness, const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a shape made of a single rectangle
 ////////////////////////////////////////////////////////////
 Shape Shape::Rectangle(float left, float top, float width, float height, const Color& color, float outline, const Color& outlineColor)
 {
@@ -235,8 +197,6 @@ Shape Shape::Rectangle(float left, float top, float width, float height, const C
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a shape made of a single rectangle
 ////////////////////////////////////////////////////////////
 Shape Shape::Rectangle(const FloatRect& rectangle, const Color& color, float outline, const Color& outlineColor)
 {
@@ -244,8 +204,6 @@ Shape Shape::Rectangle(const FloatRect& rectangle, const Color& color, float out
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a shape made of a single circle
 ////////////////////////////////////////////////////////////
 Shape Shape::Circle(float x, float y, float radius, const Color& color, float outline, const Color& outlineColor)
 {
@@ -253,8 +211,6 @@ Shape Shape::Circle(float x, float y, float radius, const Color& color, float ou
 }
 
 
-////////////////////////////////////////////////////////////
-/// Create a shape made of a single circle (use vectors)
 ////////////////////////////////////////////////////////////
 Shape Shape::Circle(const Vector2f& center, float radius, const Color& color, float outline, const Color& outlineColor)
 {
@@ -278,8 +234,6 @@ Shape Shape::Circle(const Vector2f& center, float radius, const Color& color, fl
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see Drawable::Render
 ////////////////////////////////////////////////////////////
 void Shape::Render(RenderTarget&, Renderer& renderer) const
 {
@@ -357,8 +311,6 @@ void Shape::Render(RenderTarget&, Renderer& renderer) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Compile the shape : compute its center and its outline
 ////////////////////////////////////////////////////////////
 void Shape::Compile()
 {
@@ -408,8 +360,6 @@ void Shape::Compile()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Compute the normal of a given 2D segment
 ////////////////////////////////////////////////////////////
 bool Shape::ComputeNormal(const Vector2f& p1, const Vector2f& p2, Vector2f& normal)
 {
@@ -427,8 +377,6 @@ bool Shape::ComputeNormal(const Vector2f& p1, const Vector2f& p2, Vector2f& norm
 }
 
 
-////////////////////////////////////////////////////////////
-/// Default constructor for Point
 ////////////////////////////////////////////////////////////
 Shape::Point::Point(const Vector2f& position, const Color& color, const Color& outlineColor) :
 Position  (position),

src/SFML/Graphics/Sprite.cpp

@@ -34,8 +34,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 Sprite::Sprite() :
 mySubRect   (0, 0, 1, 1),
 myIsFlippedX(false),
@@ -45,8 +43,6 @@ myIsFlippedY(false)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct the sprite from a source image
 ////////////////////////////////////////////////////////////
 Sprite::Sprite(const Image& image, const Vector2f& position, const Vector2f& scale, float rotation, const Color& color) :
 Drawable    (position, scale, rotation, color),
@@ -58,8 +54,6 @@ myIsFlippedY(false)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the image of the sprite
 ////////////////////////////////////////////////////////////
 void Sprite::SetImage(const Image& image, bool adjustToNewSize)
 {
@@ -78,8 +72,6 @@ void Sprite::SetImage(const Image& image, bool adjustToNewSize)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the sub-rectangle of the sprite inside the source image
 ////////////////////////////////////////////////////////////
 void Sprite::SetSubRect(const IntRect& rectangle)
 {
@@ -87,9 +79,6 @@ void Sprite::SetSubRect(const IntRect& rectangle)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Resize the sprite (by changing its scale factors) (take 2 values).
-/// The default size is defined by the subrect
 ////////////////////////////////////////////////////////////
 void Sprite::Resize(float width, float height)
 {
@@ -98,9 +87,6 @@ void Sprite::Resize(float width, float height)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Resize the object (by changing its scale factors) (take a 2D vector)
-/// The default size is defined by the subrect
 ////////////////////////////////////////////////////////////
 void Sprite::Resize(const Vector2f& size)
 {
@@ -108,8 +94,6 @@ void Sprite::Resize(const Vector2f& size)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Flip the sprite horizontally
 ////////////////////////////////////////////////////////////
 void Sprite::FlipX(bool flipped)
 {
@@ -117,8 +101,6 @@ void Sprite::FlipX(bool flipped)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Flip the sprite vertically
 ////////////////////////////////////////////////////////////
 void Sprite::FlipY(bool flipped)
 {
@@ -126,8 +108,6 @@ void Sprite::FlipY(bool flipped)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the source image of the sprite
 ////////////////////////////////////////////////////////////
 const Image* Sprite::GetImage() const
 {
@@ -135,8 +115,6 @@ const Image* Sprite::GetImage() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sub-rectangle of the sprite inside the source image
 ////////////////////////////////////////////////////////////
 const IntRect& Sprite::GetSubRect() const
 {
@@ -144,8 +122,6 @@ const IntRect& Sprite::GetSubRect() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the sprite size
 ////////////////////////////////////////////////////////////
 Vector2f Sprite::GetSize() const
 {
@@ -153,9 +129,6 @@ Vector2f Sprite::GetSize() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the color of a given pixel in the sprite
-/// (point is in local coordinates)
 ////////////////////////////////////////////////////////////
 Color Sprite::GetPixel(unsigned int x, unsigned int y) const
 {
@@ -176,8 +149,6 @@ Color Sprite::GetPixel(unsigned int x, unsigned int y) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see Drawable::Render
 ////////////////////////////////////////////////////////////
 void Sprite::Render(RenderTarget&, Renderer& renderer) const
 {

src/SFML/Graphics/Text.cpp

@@ -33,8 +33,6 @@
 namespace sf
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 Text::Text() :
 myFont         (&Font::GetDefaultFont()),
 myCharacterSize(30),
@@ -45,8 +43,6 @@ myRectUpdated  (true)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Construct the string from any kind of text
 ////////////////////////////////////////////////////////////
 Text::Text(const String& string, const Font& font, unsigned int characterSize) :
 myFont         (&font),
@@ -58,8 +54,6 @@ myRectUpdated  (true)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the text (from any kind of string)
 ////////////////////////////////////////////////////////////
 void Text::SetString(const String& string)
 {
@@ -68,8 +62,6 @@ void Text::SetString(const String& string)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the font of the string
 ////////////////////////////////////////////////////////////
 void Text::SetFont(const Font& font)
 {
@@ -81,8 +73,6 @@ void Text::SetFont(const Font& font)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the base size for the characters.
 ////////////////////////////////////////////////////////////
 void Text::SetCharacterSize(unsigned int size)
 {
@@ -94,9 +84,6 @@ void Text::SetCharacterSize(unsigned int size)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Set the style of the text
-/// The default style is Regular
 ////////////////////////////////////////////////////////////
 void Text::SetStyle(unsigned long style)
 {
@@ -108,8 +95,6 @@ void Text::SetStyle(unsigned long style)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the text (the returned text can be converted implicitely to any kind of string)
 ////////////////////////////////////////////////////////////
 const String& Text::GetString() const
 {
@@ -117,8 +102,6 @@ const String& Text::GetString() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the font used by the string
 ////////////////////////////////////////////////////////////
 const Font& Text::GetFont() const
 {
@@ -126,8 +109,6 @@ const Font& Text::GetFont() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the base size of characters
 ////////////////////////////////////////////////////////////
 unsigned int Text::GetCharacterSize() const
 {
@@ -135,8 +116,6 @@ unsigned int Text::GetCharacterSize() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the style of the text
 ////////////////////////////////////////////////////////////
 unsigned long Text::GetStyle() const
 {
@@ -144,10 +123,6 @@ unsigned long Text::GetStyle() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Return the visual position of the Index-th character of the string,
-/// in coordinates relative to the string
-/// (note : translation, center, rotation and scale are not applied)
 ////////////////////////////////////////////////////////////
 Vector2f Text::GetCharacterPos(std::size_t index) const
 {
@@ -192,8 +167,6 @@ Vector2f Text::GetCharacterPos(std::size_t index) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Get the string rectangle on screen
 ////////////////////////////////////////////////////////////
 FloatRect Text::GetRect() const
 {
@@ -209,8 +182,6 @@ FloatRect Text::GetRect() const
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see Drawable::Render
 ////////////////////////////////////////////////////////////
 void Text::Render(RenderTarget&, Renderer& renderer) const
 {
@@ -316,8 +287,6 @@ void Text::Render(RenderTarget&, Renderer& renderer) const
 }
 
 
-////////////////////////////////////////////////////////////
-/// Recompute the bounding rectangle of the text
 ////////////////////////////////////////////////////////////
 void Text::UpdateRect() const
 {

src/SFML/Graphics/Win32/RenderImageImplPBuffer.cpp

@@ -36,8 +36,6 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Default constructor
-////////////////////////////////////////////////////////////
 RenderImageImplPBuffer::RenderImageImplPBuffer() :
 myPBuffer      (NULL),
 myDeviceContext(NULL),
@@ -49,15 +47,11 @@ myHeight       (0)
 }
 
 
-////////////////////////////////////////////////////////////
-/// Destructor
 ////////////////////////////////////////////////////////////
 RenderImageImplPBuffer::~RenderImageImplPBuffer()
 {
     if (myContext)
-    {
         wglDeleteContext(myContext);
-    }
 
     if (myPBuffer && myDeviceContext)
     {
@@ -71,8 +65,6 @@ RenderImageImplPBuffer::~RenderImageImplPBuffer()
 }
 
 
-////////////////////////////////////////////////////////////
-/// Check whether the system supports P-Buffer or not
 ////////////////////////////////////////////////////////////
 bool RenderImageImplPBuffer::IsSupported()
 {
@@ -83,8 +75,6 @@ bool RenderImageImplPBuffer::IsSupported()
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::Create
 ////////////////////////////////////////////////////////////
 bool RenderImageImplPBuffer::Create(unsigned int width, unsigned int height, unsigned int, bool depthBuffer)
 {
@@ -159,8 +149,6 @@ bool RenderImageImplPBuffer::Create(unsigned int width, unsigned int height, uns
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::Activate
 ////////////////////////////////////////////////////////////
 bool RenderImageImplPBuffer::Activate(bool active)
 {
@@ -188,8 +176,6 @@ bool RenderImageImplPBuffer::Activate(bool active)
 }
 
 
-////////////////////////////////////////////////////////////
-/// /see RenderImageImpl::UpdateTexture
 ////////////////////////////////////////////////////////////
 void RenderImageImplPBuffer::UpdateTexture(unsigned int textureId)
 {

src/SFML/Graphics/Win32/RenderImageImplPBuffer.hpp

@@ -38,26 +38,27 @@ namespace sf
 namespace priv
 {
 ////////////////////////////////////////////////////////////
-/// Specialization of RenderImageImpl using WGL P-Buffers
+/// \brief Specialization of RenderImageImpl using WGL P-Buffers
+///
 ////////////////////////////////////////////////////////////
 class RenderImageImplPBuffer : public RenderImageImpl
 {
 public :
 
     ////////////////////////////////////////////////////////////
-    /// Default constructor
+    /// \brief Default constructor
     ///
     ////////////////////////////////////////////////////////////
     RenderImageImplPBuffer();
 
     ////////////////////////////////////////////////////////////
-    /// Destructor
+    /// \brief Destructor
     ///
     ////////////////////////////////////////////////////////////
     ~RenderImageImplPBuffer();
 
     ////////////////////////////////////////////////////////////
-    /// Check whether the system supports P-Buffer or not
+    /// \brief Check whether the system supports P-Buffer or not
     ///
     /// \return True if P-Buffer render images are supported
     ///
@@ -67,19 +68,32 @@ public :
 private :
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::Create
+    /// \brief Create the render image implementation
+    ///
+    /// \param width       Width of the image to render to
+    /// \param height      Height of the image to render to
+    /// \param textureId   OpenGL texture identifier of the target image
+    /// \param depthBuffer Is a depth buffer requested?
+    ///
+    /// \return True if creation has been successful
     ///
     ////////////////////////////////////////////////////////////
     virtual bool Create(unsigned int width, unsigned int height, unsigned int textureId, bool depthBuffer);
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::Activate
+    /// \brief Activate or deactivate the render image for rendering
+    ///
+    /// \param active True to activate, false to deactivate
+    ///
+    /// \return True on success, false on failure
     ///
     ////////////////////////////////////////////////////////////
     virtual bool Activate(bool active);
 
     ////////////////////////////////////////////////////////////
-    /// /see RenderImageImpl::UpdateTexture
+    /// \brief Update the pixels of the target texture
+    ///
+    /// \param textureId OpenGL identifier of the target texture
     ///
     ////////////////////////////////////////////////////////////
     virtual void UpdateTexture(unsigned textureId);