In-Code Documentation update

eprikazchikov · eprikazchikov · commit a6d6cffb51bd · 2024-12-28T10:54:12.000+03:00
diff --git a/doc/config.qdocconf b/doc/config.qdocconf
@@ -10,7 +10,26 @@ outputformats = HTML
 
 headerdirs += \
     ../ \
-    ../thirdparty/next/inc
+    ../engine/includes \
+	../engine/includes/components \
+	../thirdparty/next/inc \
+	../thirdparty/next/inc/math \
+	../thirdparty/next/inc/core \
+	../thirdparty/next/inc/anim \
+	../modules/uikit/includes \
+	../modules/uikit/includes/components \
+	../modules/uikit/includes/resources \
+	
+includepaths +=	\
+	../engine/includes \
+	../engine/includes/components \
+	../thirdparty/next/inc \
+	../thirdparty/next/inc/math \
+	../thirdparty/next/inc/core \
+	../thirdparty/next/inc/anim \
+	../modules/uikit/includes \
+	../modules/uikit/includes/components \
+	../modules/uikit/includes/resources \
 
 sourcedirs += \
     ../engine/src \
diff --git a/doc/htmlparser.py b/doc/htmlparser.py
@@ -149,7 +149,7 @@ def parseFile(file):
     data = f.read()
     f.close()
 
-    data = data.replace("<meta charset=\"utf-8\">", "<meta charset=\"utf-8\"/>")
+    data = re.sub('(<meta .+)(>)', '\g<1>/>', data)
     data = data.replace("&hellip;", "...")
 
     root = ET.fromstring(data)
@@ -182,13 +182,14 @@ def parseFile(file):
 
         title = root.find(".//*[@class='alignedsummary']")
         isInherit = False
-        for td in list(title.iter("td")):
-            data = "".join(td.itertext()).strip()
-            if isInherit == True:
-                classDef.inherits = data
-                isInherit = False
-            if data == "Inherits:":
-                isInherit = True
+        if title is not None:
+            for td in list(title.iter("td")):
+                data = "".join(td.itertext()).strip()
+                if isInherit == True:
+                    classDef.inherits = data
+                    isInherit = False
+                if data == "Inherits:":
+                    isInherit = True
         return classDef
     return None
 
@@ -199,7 +200,7 @@ def parseModule(file, files):
     data = f.read()
     f.close()
 
-    data = data.replace("<meta charset=\"utf-8\">", "<meta charset=\"utf-8\"/>")
+    data = re.sub('(<meta .+)(>)', '\g<1>/>', data)
     data = data.replace("&hellip;", "...")
     
     root = ET.fromstring(data)
diff --git a/doc/qdoctorst.py b/doc/qdoctorst.py
@@ -68,7 +68,7 @@ def composeMethods(classDef):
                 if method.returnType is not None:
                     if method.returnType not in defaultTypes:
                         refType = "ref"
-                        result += "{0}:{3}:`{1}<api_{1}>`{2} ".format(returnMod, method.returnType, method.reference, refType)
+                        result += "{0}:{3}:`{1}<api_{1}>` {2} ".format(returnMod, method.returnType, method.reference, refType)
                     else:
                         result += "{0}{1} ".format(returnMod, method.returnType)
 
@@ -171,7 +171,7 @@ def main():
 
                 inherits = classDef.inherits
                 if classDef.inherits is not None:
-                    inherits = ":doc:`{0}<api_{0}>`".format(inherits)
+                    inherits = ":ref:`{0}<api_{0}>`".format(inherits)
 
                 d["inheritance"] = inherits
                 d["public"] = composeTable(classDef, False)
diff --git a/engine/includes/pipelinecontext.h b/engine/includes/pipelinecontext.h
@@ -56,7 +56,7 @@ class ENGINE_EXPORT PipelineContext : public Object {
     std::list<Renderable *> &culledComponents();
     std::list<BaseLight *> &sceneLights();
 
-    std::list<Renderable *> frustumCulling(const std::array<Vector3, 8> &frustum, std::list<Renderable *> &list, AABBox &bb);
+    std::list<Renderable *> frustumCulling(const std::array<Vector3, 8> &frustum, std::list<Renderable *> &list, AABBox &box);
 
     void setPipeline(Pipeline *pipeline);
     void insertRenderTask(PipelineTask *task, PipelineTask *before = nullptr);
diff --git a/engine/includes/resources/computeshader.h b/engine/includes/resources/computeshader.h
@@ -94,7 +94,7 @@ class ENGINE_EXPORT ComputeInstance {
     void setValue(const char *name, const void *value);
 
     Texture *texture(const char *name);
-    virtual void setTexture(const char *name, Texture *value);
+    virtual void setTexture(const char *name, Texture *texture);
 
     ComputeBuffer *buffer(const char *name);
     virtual void setBuffer(const char *name, ComputeBuffer *buffer);
diff --git a/engine/src/commandbuffer.cpp b/engine/src/commandbuffer.cpp
@@ -43,6 +43,8 @@ void CommandBuffer::dispatchCompute(ComputeInstance *shader, int32_t groupsX, in
     A_UNUSED(groupsZ);
 }
 /*!
+    \fn void CommandBuffer::drawMesh(Mesh *mesh, uint32_t sub, uint32_t layer, MaterialInstance &instance)
+
     Draws a \a mesh with the specified \a sub mesh index with assigned material \a instance, and rendering \a layer.
 */
 void CommandBuffer::drawMesh(Mesh *mesh, uint32_t sub, uint32_t layer, MaterialInstance &instance) {
diff --git a/engine/src/components/armature.cpp b/engine/src/components/armature.cpp
@@ -95,6 +95,8 @@ Pose *Armature::bindPose() const {
     return m_bindPose;
 }
 /*!
+    \fn void Armature::setBindPose(Pose *pose)
+
     Sets a bind (initial) \a pose of the bone structure.
 */
 void Armature::setBindPose(Pose *pose) {
diff --git a/engine/src/components/playerinput.cpp b/engine/src/components/playerinput.cpp
@@ -73,6 +73,8 @@ ControlScheme *PlayerInput::controlScheme() const {
     return m_controlScheme;
 }
 /*!
+    \fn void PlayerInput::setControlScheme(ControlScheme *scheme)
+
     Assigns a new control \a scheme. All previous bindings and key states will be cleaned.
 */
 void PlayerInput::setControlScheme(ControlScheme *scheme) {
diff --git a/engine/src/components/textrender.cpp b/engine/src/components/textrender.cpp
@@ -78,7 +78,9 @@ Font *TextRender::font() const {
     return m_font;
 }
 /*!
-    Changes the \a font which will be used to draw a text.
+    \fn void TextRender::setFont(Font *font)
+
+    Sets the new \a font asset used to render a text.
 */
 void TextRender::setFont(Font *font) {
     if(m_font != font)  {
@@ -364,6 +366,8 @@ void TextRender::composeMesh(Font *font, Mesh *mesh, int size, const std::string
     }
 }
 /*!
+    \fn Vector2 TextRender::cursorPosition(Font *font, int size, const std::string &text, bool kerning, const Vector2 &boundaries)
+
     Returns the cursor position for rendering \a text with specified \a font and \a size.
     Developer can also enable \a kerning and specify a \a boundaries for the text.
 */
diff --git a/engine/src/components/tilemaprender.cpp b/engine/src/components/tilemaprender.cpp
@@ -56,6 +56,8 @@ TileMap *TileMapRender::tileMap() const {
     return m_tileMap;
 }
 /*!
+    \fn void TileMapRender::setTileMap(TileMap *map)
+
     Sets the tile \a map associated with this TileMapRender.
 */
 void TileMapRender::setTileMap(TileMap *map) {
diff --git a/engine/src/input.cpp b/engine/src/input.cpp
@@ -130,7 +130,7 @@ uint32_t Input::joystickCount() {
     return s_pPlatform->joystickCount();
 }
 /*!
-    Returns the states of buttons for joystick with index.
+    Returns the states of buttons for joystick with \a index.
     Please refer to Input::KeyCode to see possible buttons.
     \note This method returns a bit masked value. To retrieve the state of the required button please make bit comparison.
 
@@ -166,7 +166,7 @@ uint32_t Input::touchCount() {
     return s_pPlatform->touchCount();
 }
 /*!
-    Returns the state of touch with index.
+    Returns the state of touch with \a index.
     Please refer to Input::TouchState to see possible states.
 */
 uint32_t Input::touchState(uint32_t index) {
@@ -181,7 +181,7 @@ Vector4 Input::touchPosition(uint32_t index) {
     return s_pPlatform->touchPosition(index);
 }
 /*!
-    Returns a key code, mouse buttons
+    Converts a key \a name to code.
 */
 uint32_t Input::getCode(const std::string &name) {
     const static std::map<std::string, uint32_t> keys {
diff --git a/engine/src/pipelinecontext.cpp b/engine/src/pipelinecontext.cpp
@@ -241,7 +241,7 @@ World *PipelineContext::world() {
     return m_world;
 }
 /*!
-    Sets the curent world instance to process.
+    Sets the curent \a world instance to process.
 */
 void PipelineContext::setWorld(World *world) {
     m_world = world;
@@ -446,10 +446,10 @@ Camera *PipelineContext::currentCamera() const {
 }
 /*!
     Filters out an incoming \a list which are not in the \a frustum.
-    Returns filtered list.
+    Returns filtered list. The output parameter returns a bounding \a box for filtered objects.
 */
-list<Renderable *> PipelineContext::frustumCulling(const array<Vector3, 8> &frustum, list<Renderable *> &list, AABBox &bb) {
-    bb.extent = Vector3(-1.0f);
+list<Renderable *> PipelineContext::frustumCulling(const array<Vector3, 8> &frustum, list<Renderable *> &list, AABBox &box) {
+    box.extent = Vector3(-1.0f);
 
     Plane pl[6];
     pl[0] = Plane(frustum[1], frustum[0], frustum[4]); // top
@@ -461,10 +461,10 @@ list<Renderable *> PipelineContext::frustumCulling(const array<Vector3, 8> &frus
 
     RenderList result;
     for(auto it : list) {
-        AABBox box = it->bound();
-        if(box.extent.x < 0.0f || box.intersect(pl, 6)) {
+        AABBox bb = it->bound();
+        if(bb.extent.x < 0.0f || box.intersect(pl, 6)) {
             result.push_back(it);
-            bb.encapsulate(box);
+            box.encapsulate(bb);
         }
     }
     return result;
diff --git a/engine/src/resources/computeshader.cpp b/engine/src/resources/computeshader.cpp
@@ -12,7 +12,7 @@ namespace  {
 }
 
 /*!
-    \class MaterialInstance
+    \class ComputeInstance
     \brief The ComputeInstance class represents an instance of a ComputeShader with specific parameter values.
     \inmodule Resources
 */
@@ -133,11 +133,11 @@ Texture *ComputeInstance::texture(const char *name) {
 /*!
     Sets a \a texture parameter with specified \a name.
 */
-void ComputeInstance::setTexture(const char *name, Texture *value) {
+void ComputeInstance::setTexture(const char *name, Texture *texture) {
     A_UNUSED(name);
-    A_UNUSED(value);
+    A_UNUSED(texture);
 
-    m_textureOverride[name] = value;
+    m_textureOverride[name] = texture;
 }
 /*!
     Gets the overridden compute buffer for a specified \a name.
diff --git a/engine/src/resources/material.cpp b/engine/src/resources/material.cpp
@@ -321,7 +321,7 @@ ByteArray &MaterialInstance::rawUniformBuffer() {
 }
 
 /*!
-    Batches a material \a intance to draw using GPU instancing.
+    Batches a material \a instance to draw using GPU instancing.
 */
 void MaterialInstance::batch(MaterialInstance &instance) {
     if(m_batchBuffer.empty()) {
diff --git a/engine/src/resources/resource.cpp b/engine/src/resources/resource.cpp
@@ -21,7 +21,7 @@
 */
 
 /*!
-    \enum ResourceState
+    \enum Resource::State
 
     Status for the resource.
 
diff --git a/engine/src/resources/sprite.cpp b/engine/src/resources/sprite.cpp
@@ -34,7 +34,7 @@ Sprite::~Sprite() {
     All elements will be packed to a single sprite sheet texture using Sprite::pack() method.
     Returns the id of the new element.
 
-    \sa pack()
+    \sa packSheets()
 */
 int Sprite::addElement(Texture *texture) {
     PROFILE_FUNCTION();
diff --git a/engine/src/resources/texture.cpp b/engine/src/resources/texture.cpp
@@ -50,6 +50,13 @@ uint32_t Texture::s_maxCubemapSize = 512;
     \value Trilinear \c Texture samples are averaged and also interpolated from adjacent mipmap levels.
 */
 
+/*!
+    \enum Texture::Flags
+
+    \value Render \c This texture is used as render target in frame buffers.
+    \value Feedback \c The feedback textures can read data from GPU to CPU.
+*/
+
 /*!
     \typedef Texture::Sides
     \internal
diff --git a/engine/src/resources/visualeffect.cpp b/engine/src/resources/visualeffect.cpp
@@ -129,6 +129,8 @@ void VisualEffect::setCapacity(int capacity) {
     m_capacity = capacity;
 }
 /*!
+    \fn bool VisualEffect::local() const
+
     Returns true if particles are in local space, false otherwise.
 */
 bool VisualEffect::local() const {
diff --git a/modules/uikit/src/components/foldout.cpp b/modules/uikit/src/components/foldout.cpp
@@ -44,7 +44,7 @@ void Foldout::addWidget(Widget *widget) {
     }
 }
 /*!
-    Checks whether the foldout is currently expanded.
+    Returns true id foldout is currently expanded; otherwise returns false.
 */
 bool Foldout::isExpanded() const {
     if(m_container) {
diff --git a/modules/uikit/src/components/recttransform.cpp b/modules/uikit/src/components/recttransform.cpp
@@ -176,7 +176,7 @@ void RectTransform::setPadding(const Vector4 padding) {
 }
 /*!
     Returns true if this area is interactable with mouse; otherwise returns false.
-    \default true.
+    Returns true by the default.
 */
 bool RectTransform::mouseTracking() const {
     return m_mouseTracking;
diff --git a/modules/uikit/src/components/uiloader.cpp b/modules/uikit/src/components/uiloader.cpp
@@ -78,7 +78,7 @@ UiLoader::UiLoader() :
 
 }
 /*!
-    This function loads the UI data from an XML buffer (likely containing UI element definitions and style information).
+    This function loads the UI data from an XML \a buffer (likely containing UI element definitions and style information).
 */
 void UiLoader::fromBuffer(const std::string &buffer) {
     cleanHierarchy(this);
@@ -116,7 +116,7 @@ UiDocument *UiLoader::document() const {
     return m_document;
 }
 /*!
-    Sets the UI document to the provided document pointer and reloads the UI from the document's data buffer by calling fromBuffer().
+    Sets the UI document to the provided \a document pointer and reloads the UI from the document's data buffer by calling fromBuffer().
 */
 void UiLoader::setUiDocument(UiDocument *document) {
     if(m_document != document) {
diff --git a/thirdparty/next/src/core/bson.cpp b/thirdparty/next/src/core/bson.cpp
@@ -250,14 +250,19 @@ uint8_t type(const Variant &data) {
         VariantMap result = Bson::load(data).toMap(); // Resotoring it back
     \endcode
 */
+
 /*!
+    \fn Variant Bson::load(const ByteArray &data, MetaType::Type type)
+
     Returns deserialized binary \a data as Variant based DOM structure with expected \a type of container (can be MetaType::VARIANTLIST or MetaType::VARIANTMAP).
 */
 Variant Bson::load(const ByteArray &data, MetaType::Type type) {
     uint32_t offset = 0;
     return parse(data, offset, type, true);
 }
 /*!
+    \fn ByteArray Bson::save(const Variant &data)
+
     Returns serialized \a data as binary buffer.
 */
 ByteArray Bson::save(const Variant &data) {
diff --git a/thirdparty/next/src/core/metamethod.cpp b/thirdparty/next/src/core/metamethod.cpp
@@ -38,6 +38,7 @@
     \value Method \c Standard method can be invoked. Used for general porposes.
     \value Signal \c Method without impelementation can't be invoked. Used for Signals and Slots mechanism.
     \value Slot \c Very similar to A_METHOD but with special flag to be used for Signals and Slots mechanism.
+    \value Static \c This is a static method and doesn't requires an object to call.
 */
 /*!
     \typedef MetaMethod::Table::InvokeMem
diff --git a/thirdparty/next/src/core/metaproperty.cpp b/thirdparty/next/src/core/metaproperty.cpp
@@ -75,6 +75,8 @@ const MetaType MetaProperty::type() const {
     return MetaType(m_table->type);
 }
 /*!
+    \fn Variant MetaProperty::read(const void *object) const
+
     Returns the value as Variant which contain current property of provided \a object.
 */
 Variant MetaProperty::read(const void *object) const {
@@ -87,6 +89,8 @@ Variant MetaProperty::read(const void *object) const {
     return Variant();
 }
 /*!
+    \fn void MetaProperty::write(void *object, const Variant &value) const
+
     Tries to write a \a value as Variant to provided \a object.
 */
 void MetaProperty::write(void *object, const Variant &value) const {
diff --git a/thirdparty/next/src/core/threadpool.cpp b/thirdparty/next/src/core/threadpool.cpp
diff --git a/thirdparty/next/src/core/uri.cpp b/thirdparty/next/src/core/uri.cpp

Original file line number	Diff line number	Diff line change
`@@ -43,6 +43,8 @@ void CommandBuffer::dispatchCompute(ComputeInstance *shader, int32_t groupsX, in`
`43`	`43`	`A_UNUSED(groupsZ);`
`44`	`44`	`}`
`45`	`45`	`/*!`
	`46`	`+ \fn void CommandBuffer::drawMesh(Mesh *mesh, uint32_t sub, uint32_t layer, MaterialInstance &instance)`
	`47`	`+`
`46`	`48`	`Draws a \a mesh with the specified \a sub mesh index with assigned material \a instance, and rendering \a layer.`
`47`	`49`	`*/`
`48`	`50`	`void CommandBuffer::drawMesh(Mesh *mesh, uint32_t sub, uint32_t layer, MaterialInstance &instance) {`
Original file line number	Diff line number	Diff line change
`@@ -95,6 +95,8 @@ Pose *Armature::bindPose() const {`
`95`	`95`	`return m_bindPose;`
`96`	`96`	`}`
`97`	`97`	`/*!`
	`98`	`+ \fn void Armature::setBindPose(Pose *pose)`
	`99`	`+`
`98`	`100`	`Sets a bind (initial) \a pose of the bone structure.`
`99`	`101`	`*/`
`100`	`102`	`void Armature::setBindPose(Pose *pose) {`
Original file line number	Diff line number	Diff line change
`@@ -73,6 +73,8 @@ ControlScheme *PlayerInput::controlScheme() const {`
`73`	`73`	`return m_controlScheme;`
`74`	`74`	`}`
`75`	`75`	`/*!`
	`76`	`+ \fn void PlayerInput::setControlScheme(ControlScheme *scheme)`
	`77`	`+`
`76`	`78`	`Assigns a new control \a scheme. All previous bindings and key states will be cleaned.`
`77`	`79`	`*/`
`78`	`80`	`void PlayerInput::setControlScheme(ControlScheme *scheme) {`
Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,9 @@ Font *TextRender::font() const {`
`78`	`78`	`return m_font;`
`79`	`79`	`}`
`80`	`80`	`/*!`
`81`		`- Changes the \a font which will be used to draw a text.`
	`81`	`+ \fn void TextRender::setFont(Font *font)`
	`82`	`+`
	`83`	`+ Sets the new \a font asset used to render a text.`
`82`	`84`	`*/`
`83`	`85`	`void TextRender::setFont(Font *font) {`
`84`	`86`	`if(m_font != font) {`
`@@ -364,6 +366,8 @@ void TextRender::composeMesh(Font font, Mesh mesh, int size, const std::string`
`364`	`366`	`}`
`365`	`367`	`}`
`366`	`368`	`/*!`
	`369`	`+ \fn Vector2 TextRender::cursorPosition(Font *font, int size, const std::string &text, bool kerning, const Vector2 &boundaries)`
	`370`	`+`
`367`	`371`	`Returns the cursor position for rendering \a text with specified \a font and \a size.`
`368`	`372`	`Developer can also enable \a kerning and specify a \a boundaries for the text.`
`369`	`373`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -56,6 +56,8 @@ TileMap *TileMapRender::tileMap() const {`
`56`	`56`	`return m_tileMap;`
`57`	`57`	`}`
`58`	`58`	`/*!`
	`59`	`+ \fn void TileMapRender::setTileMap(TileMap *map)`
	`60`	`+`
`59`	`61`	`Sets the tile \a map associated with this TileMapRender.`
`60`	`62`	`*/`
`61`	`63`	`void TileMapRender::setTileMap(TileMap *map) {`