# HG changeset patch
# User Teemu Piippo <teemu@hecknology.net>
# Date 1632304544 -10800
# Node ID fb9990772357be44b705215abb6b22c5f3417510
# Parent  e8444e0d7f1a53cb17335c6512fdc2251cdde823
Add documentation to model.cpp

diff -r e8444e0d7f1a -r fb9990772357 src/model.cpp
--- a/src/model.cpp	Wed Sep 22 12:30:48 2021 +0300
+++ b/src/model.cpp	Wed Sep 22 12:55:44 2021 +0300
@@ -21,12 +21,19 @@
 #include "model.h"
 #include "modeleditcontext.h"
 
+/**
+ * @brief Constructs a model
+ * @param parent QObject parent to pass forward
+ */
 Model::Model(QObject* parent) :
 	QAbstractListModel{parent}
 {
 	connect(this, &Model::dataChanged, [&](){ this->needRecache = true; });
 }
 
+/**
+ * @returns the amount of elements in the model
+ */
 int Model::size() const
 {
 	return static_cast<int>(this->body.size());
@@ -49,17 +56,32 @@
 	}
 }
 
+/**
+ * @brief Obtains an editing context for this model.
+ * Editing contexts are used to perform modifications to the model.
+ * @return editing context
+ */
 Model::EditContext Model::edit()
 {
 	this->editCounter += 1;
 	return {*this};
 }
 
+/**
+ * @brief @overload QAbstractListModel::rowCount
+ * @return size
+ */
 int Model::rowCount(const QModelIndex&) const
 {
-	return size();
+	return this->size();
 }
 
+/**
+ * @brief @overload QAbstractListModel::data
+ * @param index
+ * @param role
+ * @return QVariant
+ */
 QVariant Model::data(const QModelIndex& index, int role) const
 {
 	const ldraw::Object* object = this->objectAt(index);
@@ -78,6 +100,11 @@
 	}
 }
 
+/**
+ * @brief Gets a property of the header
+ * @param property
+ * @return QVariant
+ */
 QVariant Model::getHeaderProperty(const HeaderProperty property)
 {
 	switch (property)
@@ -88,12 +115,24 @@
 	return {};
 }
 
+/**
+ * @brief Gets the specified property from the object at the specified index in the model.
+ * @param index Index of object in the model
+ * @param property Property to look up
+ * @return QVariant
+ */
 QVariant Model::getObjectProperty(const int index, const ldraw::Property property) const
 {
 	const ldraw::Object* object = this->body[unsigned_cast(index)].get();
 	return object->getProperty(property);
 }
 
+/**
+ * @brief Gets a list of GL polygons that are used to represent this model.
+ * @details Will build polygons if polygons are outdated.
+ * @param documents Documents to use to resolve subfile references
+ * @return vector of GL polygons
+ */
 std::vector<gl::Polygon> Model::getPolygons(DocumentManager* documents) const
 {
 	if (this->needRecache)
@@ -109,6 +148,11 @@
 	return this->cachedPolygons;
 }
 
+/**
+ * @brief Finds the position of the specified object in the model
+ * @param id Object id to look for
+ * @return model index
+ */
 QModelIndex Model::lookup(ldraw::id_t id) const
 {
 	// FIXME: This linear search will probably cause performance issues
@@ -122,11 +166,22 @@
 	return {};
 }
 
+/**
+ * @brief Gets an object id by position in the model
+ * @param index Position of the object in the model
+ * @return id
+ */
 ldraw::id_t Model::resolve(const QModelIndex& index) const
 {
 	return this->objectAt(index)->id;
 }
 
+/**
+ * @brief Gets the GL polygons of the object at the specified position in the model
+ * @param index Index of object in the model
+ * @param polygons_out Vector to add polygons into
+ * @param context Context to use to resolve subfile references
+ */
 void Model::getObjectPolygons(
 	const int index,
 	std::vector<gl::Polygon>& polygons_out,
@@ -136,17 +191,28 @@
 	object->getPolygons(polygons_out, context);
 }
 
+/**
+ * @brief Called by the editing context to signal to the model that editing is done.
+ */
 void Model::editFinished()
 {
 	this->editCounter -= 1;
 }
 
+/**
+ * @brief Called by the editing context to indicate that the specified object has been modified.
+ * @param id ID of the object that has been modified
+ */
 void Model::objectModified(ldraw::id_t id)
 {
 	const QModelIndex index = this->lookup(id);
 	Q_EMIT this->dataChanged(index, index);
 }
 
+/**
+ * @brief Adds the given object into the model.
+ * @param object r-value reference to the object
+ */
 void Model::append(ModelObjectPointer&& object)
 {
 	const int position = static_cast<int>(this->body.size());
@@ -156,6 +222,10 @@
 	this->needRecache = true;
 }
 
+/**
+ * @brief Removes the object at the specified position
+ * @param position
+ */
 void Model::remove(int position)
 {
 	if (position >= 0 and position < signed_cast(this->body.size()))
@@ -167,11 +237,21 @@
 	}
 }
 
+/**
+ * @brief Gets the object pointer at the specified position
+ * @param index Position of the object
+ * @returns object pointer
+ */
 ldraw::Object* Model::objectAt(const QModelIndex& index)
 {
 	return this->body[unsigned_cast(index.row())].get();
 }
 
+/**
+ * @brief Gets the object pointer at the specified position
+ * @param index Position of the object
+ * @returns object pointer
+ */
 const ldraw::Object* Model::objectAt(const QModelIndex& index) const
 {
 	return this->body[unsigned_cast(index.row())].get();