# HG changeset patch
# User Teemu Piippo <teemu@hecknology.net>
# Date 1631443828 -10800
# Node ID f35843351601b45492b571d7e711546208c02f59
# Parent  7c834fe36b2595ee6b7e71d904dbb4b3a53e8887
Add documentation

diff -r 7c834fe36b25 -r f35843351601 src/ui/canvas.cpp
--- a/src/ui/canvas.cpp	Sun Sep 12 12:14:32 2021 +0300
+++ b/src/ui/canvas.cpp	Sun Sep 12 13:50:28 2021 +0300
@@ -12,6 +12,11 @@
 	this->setMouseTracking(true);
 }
 
+/**
+ * @brief Handles a change of selection
+ * @param selectedIds IDs of objects to select
+ * @param deselectedIds IDs of objects to deselect.
+ */
 void Canvas::handleSelectionChange(const QSet<ldraw::id_t>& selectedIds, const QSet<ldraw::id_t>& deselectedIds)
 {
 	Q_ASSERT(not selectedIds.contains(ldraw::NULL_ID));
@@ -21,6 +26,10 @@
 	this->update();
 }
 
+/**
+ * @brief Updates vertex rendering
+ * @param document Document to get vertices from
+ */
 void Canvas::rebuildVertices(Document* document)
 {
 	if (this->vertexProgram.has_value())
@@ -53,19 +62,6 @@
 		// grid matrix.
 		this->worldPosition = this->gridMatrix * glm::vec4{*this->worldPosition, 1};
 	}
-	/*
-	if (this->worldPosition.has_value())
-	{
-		this->newStatusText("Position: (%1, %2, %3)"_q
-			.arg(toDouble(this->worldPosition->x))
-			.arg(toDouble(this->worldPosition->y))
-			.arg(toDouble(this->worldPosition->z)));
-	}
-	else
-	{
-		this->newStatusText("Position: <none>"_q);
-	}
-	*/
 	Q_EMIT this->mouseMove(this, event);
 	PartRenderer::mouseMoveEvent(event);
 	this->update();
@@ -121,13 +117,7 @@
 	});
 	PartRenderer::initializeGL();
 	// Set up XZ grid matrix
-	this->gridMatrix = glm::mat4{
-		{1, 0, 0, 0},
-		{0, 0, 1, 0},
-		{0, 1, 0, 0},
-		{0, 0, 0, 1}
-	};
-	this->updateGridMatrix();
+	this->setGridMatrix({{1, 0, 0, 0}, {0, 0, 1, 0}, {0, 1, 0, 0}, {0, 0, 0, 1}});
 }
 
 void Canvas::paintGL()
@@ -233,6 +223,11 @@
 	}
 }
 
+/**
+ * @brief Draws a polygon to where the specified vector of 3D points would appear on the screen.
+ * @param painter Painter to use to draw with
+ * @param points 3D points to render
+ */
 void Canvas::drawWorldPolygon(QPainter* painter, const std::vector<glm::vec3> &points)
 {
 	QVector<QPointF> points2d;
@@ -244,6 +239,10 @@
 	painter->drawPolygon(QPolygonF{points2d});
 }
 
+/**
+ * @brief Gets the current position of the cursor in the model
+ * @return 3D vector
+ */
 const std::optional<glm::vec3>& Canvas::getWorldPosition() const
 {
 	return this->worldPosition;
@@ -261,24 +260,33 @@
 	const float angle_y = std::abs(glm::dot(vector_y, cameraDirection));
 	if (angle_x < angle_y)
 	{
-		this->gridMatrix = glm::rotate(this->gridMatrix, PI<float> / 2, glm::vec3{1, 0, 0});
+		this->setGridMatrix(glm::rotate(this->gridMatrix, PI<float> / 2, glm::vec3{1, 0, 0}));
 	}
 	else
 	{
-		this->gridMatrix = glm::rotate(this->gridMatrix, PI<float> / 2, glm::vec3{0, 1, 0});
+		this->setGridMatrix(glm::rotate(this->gridMatrix, PI<float> / 2, glm::vec3{0, 1, 0}));
 	}
-	this->updateGridMatrix();
 	this->update();
 }
 
+/**
+ * @brief Paints a circle at where @c worldPoint is located on the screen.
+ * @param painter Painter to use to render
+ * @param worldPoint Point to render
+ */
 void Canvas::drawWorldPoint(QPainter* painter, const glm::vec3& worldPoint) const
 {
 	const QPointF center = this->modelToScreenCoordinates(worldPoint);
 	painter->drawEllipse(geom::inscribe(geom::CircleF{center, 5}));
 }
 
-void Canvas::updateGridMatrix()
+/**
+ * @brief Changes the grid matrix to the one specified. Updates relevant member variables.
+ * @param newMatrix New matrix to use
+ */
+void Canvas::setGridMatrix(const glm::mat4& newMatrix)
 {
+	this->gridMatrix = newMatrix;
 	const geom::Triangle triangle {
 		this->gridMatrix * glm::vec4{0, 0, 0, 1},
 		this->gridMatrix * glm::vec4{1, 0, 0, 1},
@@ -288,6 +296,10 @@
 	this->gridProgram->setGridMatrix(this->gridMatrix);
 }
 
+/**
+ * @brief Gets the current camera vector, i.e. the vector from the camera to the grid origin.
+ * @return vector
+ */
 glm::vec3 Canvas::cameraVector() const
 {
 	// Find out where the grid is projected on the screen
@@ -297,8 +309,8 @@
 }
 
 /**
- * @brief Calculates if the screen is perpendicular to the current grid
- * @return yes no
+ * @brief Calculates whether the screen is perpendicular to the current grid
+ * @return bool
  */
 bool Canvas::isGridPerpendicularToScreen(float threshold) const
 {
@@ -313,6 +325,9 @@
 	return std::abs(dot) < threshold;
 }
 
+/**
+ * @brief Clears the selection.
+ */
 void Canvas::clearSelection()
 {
 	this->selection.clear();
@@ -321,6 +336,10 @@
 	this->update();
 }
 
+/**
+ * @brief Adds an object to selection.
+ * @param id ID of object to add
+ */
 void Canvas::addToSelection(ldraw::id_t id)
 {
 	this->selection.insert(id);