From 7b3f70a08bfd192242914e25ca9ed482552256eb Mon Sep 17 00:00:00 2001
From: Kim Kulling <kimkulling@users.noreply.github.com>
Date: Thu, 9 Feb 2023 21:12:21 +0100
Subject: [PATCH] Add skeleton doc

---
 include/assimp/mesh.h | 44 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 36 insertions(+), 8 deletions(-)

diff --git a/include/assimp/mesh.h b/include/assimp/mesh.h
index 16cd4fa3c..fd2f3218e 100644
--- a/include/assimp/mesh.h
+++ b/include/assimp/mesh.h
@@ -952,17 +952,32 @@ struct aiMesh {
 #endif // __cplusplus
 };
 
+*
+ * @brief  A skeleton bone represents a single bone is a skeleton structure.
+ *
+ * Skeleton-Animations can be represented via a skeleton struct, which describes
+ * a hierarchical tree assembled from skeleton bones. A bone is linked to a mesh.
+ * The bone knows its parent bone. If there is no parent bone the parent id is
+ * marked with -1.
+ * The skeleton-bone stores a pointer to its used armature. If there is no
+ * armature this value if set to nullptr.
+ * A skeleton bone stores its offset-matrix, which is the absolute transformation
+ * for the bone. The bone stores the locale transformation to its parent as well.
+ * You can compute the offset matrix by multiplying the hierarchy like:
+ * Tree: s1 -> s2 -> s3
+ * Offset-Matrix s3 = locale-s3 * locale-s2 * locale-s1
+ */
 struct aiSkeletonBone {
     /// The parent bone index, is -1 one if this bone represents the root bone.
     int mParent;
 
 
 #ifndef ASSIMP_BUILD_NO_ARMATUREPOPULATE_PROCESS
-    /// The bone armature node - used for skeleton conversion
+    /// @brief The bone armature node - used for skeleton conversion
     /// you must enable aiProcess_PopulateArmatureData to populate this
     C_STRUCT aiNode *mArmature;
 
-    /// The bone node in the scene - used for skeleton conversion
+    /// @brief The bone node in the scene - used for skeleton conversion
     /// you must enable aiProcess_PopulateArmatureData to populate this
     C_STRUCT aiNode *mNode;
 
@@ -993,6 +1008,7 @@ struct aiSkeletonBone {
     C_STRUCT aiMatrix4x4 mLocalMatrix;
 
 #ifdef __cplusplus
+    ///	@brief The class constructor.
     aiSkeletonBone() :
             mParent(-1),
 #ifndef ASSIMP_BUILD_NO_ARMATUREPOPULATE_PROCESS
@@ -1007,6 +1023,7 @@ struct aiSkeletonBone {
         // empty
     }
 
+    /// @brief The class destructor.
     ~aiSkeletonBone() {
         delete[] mWeights;
         mWeights = nullptr;
@@ -1014,34 +1031,45 @@ struct aiSkeletonBone {
 #endif // __cplusplus
 };
 /**
- *  @brief
+ * @brief A skeleton represents the bone hierarchy of an animation.
+ *
+ * Skeleton animations can be described as a tree of bones:
+ *                  root
+ *                    |
+ *                  node1
+ *                  /   \
+ *               node3  node4
+ * If you want to calculate the transformation of node three you need to compute the
+ * transformation hierarchy for the transformation chain of node3:
+ * root->node1->node3
+ * Each node is represented as a skeleton instance.
  */
 struct aiSkeleton {
     /**
-     *
+     *  @brief The name of the skeleton instance.
      */
     C_STRUCT aiString mName;
 
     /**
-     *
+     *  @brief  The number of bones in the skeleton.
      */
     unsigned int mNumBones;
 
     /**
-     *
+     *  @brief The bone instance in the skeleton.
      */
     C_STRUCT aiSkeletonBone **mBones;
 
 #ifdef __cplusplus
     /**
-     *
+     *  @brief The class constructor.
      */
     aiSkeleton() AI_NO_EXCEPT : mName(), mNumBones(0), mBones(nullptr) {
         // empty
     }
 
     /**
-     *
+     *  @brief  The class destructor.
      */
     ~aiSkeleton() {
         delete[] mBones;