Document Point and Rect

SDL2pp/Point.hh

@@ -29,19 +29,86 @@
 
 namespace SDL2pp {
 
-class Point : public SDL_Point{
+////////////////////////////////////////////////////////////
+/// \brief 2D point
+///
+/// \ingroup geometry
+///
+/// \headerfile SDL2pp/Point.hh
+///
+/// This class is public-derived from SDL_Point structure,
+/// may generally used as it if passed via pointer or
+/// reference. It also supports direct access to x and y
+/// members.
+///
+////////////////////////////////////////////////////////////
+class Point : public SDL_Point {
 public:
+	////////////////////////////////////////////////////////////
+	/// \brief Default constructor
+	///
+	/// Creates a Point(0, 0)
+	///
+	////////////////////////////////////////////////////////////
 	Point();
+
+	////////////////////////////////////////////////////////////
+	/// \brief Construct the point from given coordinates
+	///
+	/// \param nx X coordinate
+	/// \param ny Y coordinate
+	///
+	////////////////////////////////////////////////////////////
 	Point(int nx, int ny);
 
 	SDL2PP_DEPRECATED static Optional<Point> Null();
 
+	////////////////////////////////////////////////////////////
+	/// \brief Copy constructor
+	///
+	////////////////////////////////////////////////////////////
 	Point(const Point&) noexcept = default;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Move constructor
+	///
+	////////////////////////////////////////////////////////////
 	Point(Point&&) noexcept = default;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Assignment operator
+	///
+	/// \returns Reference to self
+	///
+	////////////////////////////////////////////////////////////
 	Point& operator=(const Point&) noexcept = default;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Move assignment operator
+	///
+	/// \returns Reference to self
+	///
+	////////////////////////////////////////////////////////////
 	Point& operator=(Point&&) noexcept = default;
 
+	////////////////////////////////////////////////////////////
+	/// \brief Equality operator
+	///
+	/// \param other Point to compare to
+	///
+	/// \returns whether two points are identical
+	///
+	////////////////////////////////////////////////////////////
 	bool operator==(const Point& other) const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Inequality operator
+	///
+	/// \param other Point to compare to
+	///
+	/// \returns whether two points are not identical
+	///
+	////////////////////////////////////////////////////////////
 	bool operator!=(const Point& other) const;
 
 	SDL2PP_DEPRECATED SDL_Point* Get();
@@ -49,16 +116,76 @@ public:
 
 	SDL2PP_DEPRECATED bool IsNull() const;
 
+	////////////////////////////////////////////////////////////
+	/// \brief Get X coordinate of the point
+	///
+	/// \returns X coordinate of the point
+	///
+	////////////////////////////////////////////////////////////
 	int GetX() const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Set X coordinate of the point
+	///
+	/// \param nx new X coordinate value
+	///
+	////////////////////////////////////////////////////////////
 	void SetX(int nx);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Get Y coordinate of the point
+	///
+	/// \returns Y coordinate of the point
+	///
+	////////////////////////////////////////////////////////////
 	int GetY() const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Set Y coordinate of the point
+	///
+	/// \param ny new Y coordinate value
+	///
+	////////////////////////////////////////////////////////////
 	void SetY(int ny);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Get sum of two points
+	///
+	/// \param other point to add
+	///
+	/// \returns a new Point representing memberwise addition of two points
+	///
+	////////////////////////////////////////////////////////////
 	Point operator+(const Point& other) const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Get subtraction of two points
+	///
+	/// \param other point to subtract
+	///
+	/// \returns a new Point representing memberwise subtraction of two points
+	///
+	////////////////////////////////////////////////////////////
 	Point operator-(const Point& other) const;
 
+	////////////////////////////////////////////////////////////
+	/// \brief Add another point
+	///
+	/// \param other point to add to the current one
+	///
+	/// \returns reference to self
+	///
+	////////////////////////////////////////////////////////////
 	Point& operator+=(const Point& other);
+
+	////////////////////////////////////////////////////////////
+	/// \brief Substact another point
+	///
+	/// \param other point to subtract from the current one
+	///
+	/// \returns reference to self
+	///
+	////////////////////////////////////////////////////////////
 	Point& operator-=(const Point& other);
 };
 

SDL2pp/Rect.hh

@@ -33,53 +33,254 @@ namespace SDL2pp {
 
 class Point;
 
+////////////////////////////////////////////////////////////
+/// \brief 2D rectangle
+///
+/// \ingroup geometry
+///
+/// \headerfile SDL2pp/Rect.hh
+///
+/// This class is public-derived from SDL_Rect structure,
+/// may generally used as it if passed via pointer or
+/// reference. It also supports direct access to x, y, w
+/// and h members.
+///
+////////////////////////////////////////////////////////////
 class Rect : public SDL_Rect {
 public:
+	////////////////////////////////////////////////////////////
+	/// \brief Default constructor
+	///
+	/// Creates a Rect(0, 0, 0, 0)
+	///
+	////////////////////////////////////////////////////////////
 	Rect();
+
+	////////////////////////////////////////////////////////////
+	/// \brief Construct the rect from given corner coordinates, width and height
+	///
+	/// \param x X coordinate of the top left rectangle corner
+	/// \param y Y coordinate of the top left rectangle corner
+	/// \param w width of the rectangle
+	/// \param h height of the rectangle
+	///
+	////////////////////////////////////////////////////////////
 	Rect(int x, int y, int w, int h);
 
 	SDL2PP_DEPRECATED static Optional<Rect> Null();
 
+	////////////////////////////////////////////////////////////
+	/// \brief Construct the rect from given center coordinates, width and height
+	///
+	/// \param cx X coordinate of the rectangle center
+	/// \param cy Y coordinate of the rectangle center
+	/// \param w width of the rectangle
+	/// \param h height of the rectangle
+	///
+	////////////////////////////////////////////////////////////
 	static Rect FromCenter(int cx, int cy, int w, int h);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Copy constructor
+	///
+	////////////////////////////////////////////////////////////
 	Rect(const Rect&) noexcept = default;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Move constructor
+	///
+	////////////////////////////////////////////////////////////
 	Rect(Rect&&) noexcept = default;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Assignment operator
+	///
+	/// \returns Reference to self
+	///
+	////////////////////////////////////////////////////////////
 	Rect& operator=(const Rect&) noexcept = default;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Move assignment operator
+	///
+	/// \returns Reference to self
+	///
+	////////////////////////////////////////////////////////////
 	Rect& operator=(Rect&&) noexcept = default;
 
+	////////////////////////////////////////////////////////////
+	/// \brief Equality operator
+	///
+	/// \param other Rect to compare to
+	///
+	/// \returns whether two rectangles are identical
+	///
+	////////////////////////////////////////////////////////////
 	bool operator==(const Rect& other) const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Inequality operator
+	///
+	/// \param other Rect to compare to
+	///
+	/// \returns whether two rectangles are not identical
+	///
+	////////////////////////////////////////////////////////////
 	bool operator!=(const Rect& other) const;
 
-	// deprecated
 	SDL2PP_DEPRECATED SDL_Rect* Get();
 	SDL2PP_DEPRECATED const SDL_Rect* Get() const;
 
 	SDL2PP_DEPRECATED bool IsNull() const;
 
+	////////////////////////////////////////////////////////////
+	/// \brief Get X coordinate of the rect corner
+	///
+	/// \returns X coordinate of the rect corner
+	///
+	////////////////////////////////////////////////////////////
 	int GetX() const;
-	void SetX(int x);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Set X coordinate of the rect corner
+	///
+	/// \param nx new X coordinate value
+	///
+	////////////////////////////////////////////////////////////
+	void SetX(int nx);
+
+	////////////////////////////////////////////////////////////
+	/// \brief Get Y coordinate of the rect corner
+	///
+	/// \returns Y coordinate of the rect corner
+	///
+	////////////////////////////////////////////////////////////
 	int GetY() const;
-	void SetY(int y);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Set Y coordinate of the rect corner
+	///
+	/// \param ny new Y coordinate value
+	///
+	////////////////////////////////////////////////////////////
+	void SetY(int ny);
+
+	////////////////////////////////////////////////////////////
+	/// \brief Get width of the rect
+	///
+	/// \returns width of the rect
+	///
+	////////////////////////////////////////////////////////////
 	int GetW() const;
-	void SetW(int w);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Set width of the rect
+	///
+	/// \param nw new width of the rect
+	///
+	////////////////////////////////////////////////////////////
+	void SetW(int nw);
+
+	////////////////////////////////////////////////////////////
+	/// \brief Get height of the rect
+	///
+	/// \returns height of the rect
+	///
+	////////////////////////////////////////////////////////////
 	int GetH() const;
-	void SetH(int h);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Set height of the rect
+	///
+	/// \param nh new height of the rect
+	///
+	////////////////////////////////////////////////////////////
+	void SetH(int nh);
+
+	////////////////////////////////////////////////////////////
+	/// \brief Get X coordinate of the rect second corner
+	///
+	/// \returns X coordinate of the rect second corner
+	///
+	////////////////////////////////////////////////////////////
 	int GetX2() const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Set X coordinate of the rect second corner
+	///
+	/// \param x2 new X coordinate value
+	///
+	////////////////////////////////////////////////////////////
 	void SetX2(int x2);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Get Y coordinate of the rect second corner
+	///
+	/// \returns Y coordinate of the rect second corner
+	///
+	/// This modifies rectangle width internally
+	///
+	////////////////////////////////////////////////////////////
 	int GetY2() const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Set Y coordinate of the rect second corner
+	///
+	/// \param y2 new Y coordinate value
+	///
+	/// This modifies rectangle height internally
+	///
+	////////////////////////////////////////////////////////////
 	void SetY2(int y2);
 
+	////////////////////////////////////////////////////////////
+	/// \brief Check whether the rect contains given point
+	///
+	/// \param point point to check
+	///
+	/// \returns whether the point is contained in the rect
+	///
+	////////////////////////////////////////////////////////////
 	bool Contains(const Point& point) const;
 
+	////////////////////////////////////////////////////////////
+	/// \brief Get rectangle moved by a given offset
+	///
+	/// \param offset Point specifying an offset
+	///
+	/// \returns moved rectangle
+	///
+	////////////////////////////////////////////////////////////
 	Rect operator+(const Point& offset) const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Get rectangle moved by an opposite of given offset
+	///
+	/// \param offset Point specifying an offset
+	///
+	/// \returns moved rectangle
+	///
+	////////////////////////////////////////////////////////////
+	Rect operator-(const Point& offset) const;
+
+	////////////////////////////////////////////////////////////
+	/// \brief Move by then given offset
+	///
+	/// \param offset Point specifying an offset
+	///
+	/// \returns reference to self
+	///
+	////////////////////////////////////////////////////////////
 	Rect& operator+=(const Point& offset);
 
-	Rect operator-(const Point& offset) const;
+	////////////////////////////////////////////////////////////
+	/// \brief Move by an opposite of the given offset
+	///
+	/// \param offset Point specifying an offset
+	///
+	/// \returns reference to self
+	///
+	////////////////////////////////////////////////////////////
 	Rect& operator-=(const Point& offset);
 };
 

SDL2pp/SDL2pp.hh

@@ -74,9 +74,9 @@
 #include <SDL2pp/Texture.hh>
 
 ////////////////////////////////////////////////////////////
-/// \defgroup rect Rects and Points
+/// \defgroup geometry 2D geometry
 ///
-/// \brief Rectangle and point functions
+/// \brief 2D rectangle and point functions
 ///
 /// \ingroup graphics
 ///