Merge pull request #467 from PellelNitram/code_documentation

Code documentation

.gitignore

@@ -40,3 +40,7 @@ nbproject/
 .idea
 cmake-build-debug
 cmake-build-release
+
+# API Documentation
+doc/html
+doc/latex

README.md

@@ -104,6 +104,25 @@ If you want to install desktop file and thumbnailer execute:
 make desktop-install
 ```
 
+## Code documentation
+
+The code documentation is generated using Doxygen.
+
+In order to generate the documentation yourself, first install Doxygen and graphviz, i.e.
+
+```bash
+sudo apt install doxygen
+sudo apt install graphviz
+```
+
+on Debian or Ubuntu. Finally, type in `doxygen` in the root directory of the repository.
+The documentation can be found in `doc/html` and `doc/latex`. Conveniently display the
+documentation with `python3 -m http.server 8000` and visit the shown URL to view the
+documentation.
+
+The website https://cypax.net/tutorials/doxygen/ provides a good introduction to Doxygen
+and how to document code with it.
+
 ## Fileformat
 The fileformat *.xopp is an XML which is .gz compressed. PDFs are not embedded
 into the file, so if the PDF is deleted, the background is lost.

src/control/tools/EditSelection.cpp

@@ -23,6 +23,7 @@
 #include <serializing/ObjectInputStream.h>
 
 #include <iostream>
+#include <math.h>
 using std::cout;
 using std::endl;
 

src/model/Point.h

@@ -13,28 +13,88 @@
 
 #include <XournalType.h>
 
+/**
+ * @class Point
+ * @brief Representation of a point.
+ */
 class Point
 {
 public:
+
+	/**
+	 * @brief Default constructor.
+	 */
 	Point();
+
+	/**
+	 * @brief Copy constructor.
+	 * @param p The point to copy.
+	 */
 	Point(const Point& p);
+
+	/**
+	 * @brief Point from two values.
+	 * @param x X value of the point.
+	 * @param y Y value of the point.
+	 */
 	Point(double x, double y);
+
+	/**
+	 * @brief Point from three values.
+	 * @param x X value of the point.
+	 * @param y Y value of the point.
+	 * @param z Z value of the point. This denotes the pressure sensitivity.
+	 */
 	Point(double x, double y, double z);
+
 	virtual ~Point();
 
 public:
+
+	/**
+	 * @brief Compute the distance to another point.
+	 * @param p The other point.
+	 * @return The Euclidean distance to the other point.
+	 */
 	double lineLengthTo(const Point& p);
+
+	/**
+	 * @brief The slope to another point.
+	 * @param p The other point.
+	 */
 	double slopeTo(const Point& p);
+
+	/**
+	 * @brief Compute new Point in the direction from this to another Point.
+	 * @param p The other Point.
+	 * @param length The line length or vector length.
+	 * @return The new Point.
+	 */
 	Point lineTo(const Point& p, double length);
+
+	/**
+	 * @brief Compare if this Point has the same position as another Point.
+	 * @param p The other Point.
+	 * @return True if the coordinates are equal. False otherwise.
+	 */
 	bool equalsPos(const Point& p);
 
 public:
 	XOJ_TYPE_ATTRIB;
 
+	/**
+	 * @brief Private storage for x coordinate.
+	 */
 	double x;
+
+	/**
+	 * @brief Private storage for y coordinate.
+	 */
 	double y;
 
-	// pressure
+	/**
+	 * @brief Private storage for pressure.
+	 */
 	double z;
 
 	static constexpr double NO_PRESURE = -1;