Cleanup: move public doc-strings into headers for 'blenkernel'

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 83 insertions, 0 deletions

diff --git a/source/blender/blenkernel/BKE_key.h b/source/blender/blenkernel/BKE_key.h
index cb4fc607703..305cb62179d 100644
--- a/source/blender/blenkernel/BKE_key.h
+++ b/source/blender/blenkernel/BKE_key.h
@@ -36,21 +36,44 @@ struct Object;
 extern "C" {
 #endif
 
+/**
+ * Free (or release) any data used by this shapekey (does not free the key itself).
+ */
 void BKE_key_free_data(struct Key *key);
 void BKE_key_free_nolib(struct Key *key);
 struct Key *BKE_key_add(struct Main *bmain, struct ID *id);
+/**
+ * Sort shape keys after a change.
+ * This assumes that at most one key was moved,
+ * which is a valid assumption for the places it's currently being called.
+ */
 void BKE_key_sort(struct Key *key);
 
 void key_curve_position_weights(float t, float data[4], int type);
+/**
+ * First derivative.
+ */
 void key_curve_tangent_weights(float t, float data[4], int type);
+/**
+ * Second derivative.
+ */
 void key_curve_normal_weights(float t, float data[4], int type);
 
+/**
+ * Returns key coordinates (+ tilt) when key applied, NULL otherwise.
+ */
 float *BKE_key_evaluate_object_ex(struct Object *ob, int *r_totelem, float *arr, size_t arr_size);
 float *BKE_key_evaluate_object(struct Object *ob, int *r_totelem);
 
+/**
+ * \param shape_index: The index to use or all (when -1).
+ */
 int BKE_keyblock_element_count_from_shape(const struct Key *key, const int shape_index);
 int BKE_keyblock_element_count(const struct Key *key);
 
+/**
+ * \param shape_index: The index to use or all (when -1).
+ */
 size_t BKE_keyblock_element_calc_size_from_shape(const struct Key *key, const int shape_index);
 size_t BKE_keyblock_element_calc_size(const struct Key *key);
 
@@ -60,18 +83,43 @@ struct Key **BKE_key_from_id_p(struct ID *id);
 struct Key *BKE_key_from_id(struct ID *id);
 struct Key **BKE_key_from_object_p(const struct Object *ob);
 struct Key *BKE_key_from_object(const struct Object *ob);
+/**
+ * Only the active key-block.
+ */
 struct KeyBlock *BKE_keyblock_from_object(struct Object *ob);
 struct KeyBlock *BKE_keyblock_from_object_reference(struct Object *ob);
 
 struct KeyBlock *BKE_keyblock_add(struct Key *key, const char *name);
+/**
+ * \note sorting is a problematic side effect in some cases,
+ * better only do this explicitly by having its own function,
+ *
+ * \param key: The key datablock to add to.
+ * \param name: Optional name for the new keyblock.
+ * \param do_force: always use ctime even for relative keys.
+ */
 struct KeyBlock *BKE_keyblock_add_ctime(struct Key *key, const char *name, const bool do_force);
+/**
+ * Get the appropriate #KeyBlock given an index.
+ */
 struct KeyBlock *BKE_keyblock_from_key(struct Key *key, int index);
+/**
+ * Get the appropriate #KeyBlock given a name to search for.
+ */
 struct KeyBlock *BKE_keyblock_find_name(struct Key *key, const char name[]);
+/**
+ * \brief copy shape-key attributes, but not key data.or name/UID
+ */
 void BKE_keyblock_copy_settings(struct KeyBlock *kb_dst, const struct KeyBlock *kb_src);
+/**
+ * Get RNA-Path for 'value' setting of the given shape-key.
+ * \note the user needs to free the returned string once they're finish with it.
+ */
 char *BKE_keyblock_curval_rnapath_get(struct Key *key, struct KeyBlock *kb);
 
 /* conversion functions */
 /* NOTE: 'update_from' versions do not (re)allocate mem in kb, while 'convert_from' do. */
+
 void BKE_keyblock_update_from_lattice(struct Lattice *lt, struct KeyBlock *kb);
 void BKE_keyblock_convert_from_lattice(struct Lattice *lt, struct KeyBlock *kb);
 void BKE_keyblock_convert_to_lattice(struct KeyBlock *kb, struct Lattice *lt);
@@ -88,6 +136,15 @@ void BKE_keyblock_convert_to_curve(struct KeyBlock *kb, struct Curve *cu, struct
 void BKE_keyblock_update_from_mesh(struct Mesh *me, struct KeyBlock *kb);
 void BKE_keyblock_convert_from_mesh(struct Mesh *me, struct Key *key, struct KeyBlock *kb);
 void BKE_keyblock_convert_to_mesh(struct KeyBlock *kb, struct Mesh *me);
+/**
+ * Computes normals (vertices, polygons and/or loops ones) of given mesh for given shape key.
+ *
+ * \param kb: the KeyBlock to use to compute normals.
+ * \param mesh: the Mesh to apply key-block to.
+ * \param r_vertnors: if non-NULL, an array of vectors, same length as number of vertices.
+ * \param r_polynors: if non-NULL, an array of vectors, same length as number of polygons.
+ * \param r_loopnors: if non-NULL, an array of vectors, same length as number of loops.
+ */
 void BKE_keyblock_mesh_calc_normals(struct KeyBlock *kb,
                                     struct Mesh *mesh,
                                     float (*r_vertnors)[3],
@@ -107,28 +164,54 @@ void BKE_keyblock_update_from_offset(struct Object *ob,
                                      const float (*ofs)[3]);
 
 /* other management */
+
+/**
+ * Move shape key from org_index to new_index. Safe, clamps index to valid range,
+ * updates reference keys, the object's active shape index,
+ * the 'frame' value in case of absolute keys, etc.
+ * Note indices are expected in real values (not 'fake' shapenr +1 ones).
+ *
+ * \param org_index: if < 0, current object's active shape will be used as skey to move.
+ * \return true if something was done, else false.
+ */
 bool BKE_keyblock_move(struct Object *ob, int org_index, int new_index);
 
+/**
+ * Check if given key-block (as index) is used as basis by others in given key.
+ */
 bool BKE_keyblock_is_basis(struct Key *key, const int index);
 
 /* -------------------------------------------------------------------- */
 /** \name Key-Block Data Access
  * \{ */
 
+/**
+ * \param shape_index: The index to use or all (when -1).
+ */
 void BKE_keyblock_data_get_from_shape(const struct Key *key,
                                       float (*arr)[3],
                                       const int shape_index);
 void BKE_keyblock_data_get(const struct Key *key, float (*arr)[3]);
 
+/**
+ * Set the data to all key-blocks (or shape_index if != -1).
+ */
 void BKE_keyblock_data_set_with_mat4(struct Key *key,
                                      const int shape_index,
                                      const float (*coords)[3],
                                      const float mat[4][4]);
+/**
+ * Set the data for all key-blocks (or shape_index if != -1),
+ * transforming by \a mat.
+ */
 void BKE_keyblock_curve_data_set_with_mat4(struct Key *key,
                                            const struct ListBase *nurb,
                                            const int shape_index,
                                            const void *data,
                                            const float mat[4][4]);
+/**
+ * Set the data for all key-blocks (or shape_index if != -1).
+ */
 void BKE_keyblock_data_set(struct Key *key, const int shape_index, const void *data);
 
 /** \} */