1 files changed, 21 insertions, 0 deletions

diff --git a/source/blender/blenkernel/BKE_mesh_tangent.h b/source/blender/blenkernel/BKE_mesh_tangent.h
index 96eaa23ce71..39d4072085c 100644
--- a/source/blender/blenkernel/BKE_mesh_tangent.h
+++ b/source/blender/blenkernel/BKE_mesh_tangent.h
@@ -25,6 +25,12 @@ extern "C" {
 
 struct ReportList;
 
+/**
+ * Compute simplified tangent space normals, i.e.
+ * tangent vector + sign of bi-tangent one, which combined with
+ * split normals can be used to recreate the full tangent space.
+ * NOTE: * The mesh should be made of only tris and quads!
+ */
 void BKE_mesh_calc_loop_tangent_single_ex(const struct MVert *mverts,
                                           const int numVerts,
                                           const struct MLoop *mloops,
@@ -35,11 +41,20 @@ void BKE_mesh_calc_loop_tangent_single_ex(const struct MVert *mverts,
                                           const struct MPoly *mpolys,
                                           const int numPolys,
                                           struct ReportList *reports);
+/**
+ * Wrapper around BKE_mesh_calc_loop_tangent_single_ex, which takes care of most boiling code.
+ * \note
+ * - There must be a valid loop's CD_NORMALS available.
+ * - The mesh should be made of only tris and quads!
+ */
 void BKE_mesh_calc_loop_tangent_single(struct Mesh *mesh,
                                        const char *uvmap,
                                        float (*r_looptangents)[4],
                                        struct ReportList *reports);
 
+/**
+ * See: #BKE_editmesh_loop_tangent_calc (matching logic).
+ */
 void BKE_mesh_calc_loop_tangent_ex(const struct MVert *mvert,
                                    const struct MPoly *mpoly,
                                    const uint mpoly_len,
@@ -71,6 +86,12 @@ void BKE_mesh_add_loop_tangent_named_layer_for_uv(struct CustomData *uv_data,
                                                   const char *layer_name);
 
 #define DM_TANGENT_MASK_ORCO (1 << 9)
+/**
+ * Here we get some useful information such as active uv layer name and
+ * search if it is already in tangent_names.
+ * Also, we calculate tangent_mask that works as a descriptor of tangents state.
+ * If tangent_mask has changed, then recalculate tangents.
+ */
 void BKE_mesh_calc_loop_tangent_step_0(const struct CustomData *loopData,
                                        bool calc_active_tangent,
                                        const char (*tangent_names)[64],