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

- 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, 51 insertions, 0 deletions

diff --git a/source/blender/blenlib/BLI_rect.h b/source/blender/blenlib/BLI_rect.h
index 7950596933c..f4b1d051d16 100644
--- a/source/blender/blenlib/BLI_rect.h
+++ b/source/blender/blenlib/BLI_rect.h
@@ -34,12 +34,28 @@ struct rcti;
 extern "C" {
 #endif
 
+/**
+ * Determine if a `rect` is empty.
+ * An empty `rect` is one with a zero (or negative) width or height.
+ *
+ * \return True if \a rect is empty.
+ */
 bool BLI_rcti_is_empty(const struct rcti *rect);
 bool BLI_rctf_is_empty(const struct rctf *rect);
 void BLI_rctf_init(struct rctf *rect, float xmin, float xmax, float ymin, float ymax);
 void BLI_rcti_init(struct rcti *rect, int xmin, int xmax, int ymin, int ymax);
+/**
+ * Check if X-min and Y-min are less than or equal to X-max and Y-max, respectively.
+ * If this returns false, #BLI_rctf_sanitize() can be called to address this.
+ *
+ * This is not a hard constraint or invariant for rectangles, in some cases it may be useful to
+ * have max < min. Usually this is what you'd want though.
+ */
 bool BLI_rctf_is_valid(const struct rctf *rect);
 bool BLI_rcti_is_valid(const struct rcti *rect);
+/**
+ * Ensure X-min and Y-min are less than or equal to X-max and Y-max, respectively.
+ */
 void BLI_rctf_sanitize(struct rctf *rect);
 void BLI_rcti_sanitize(struct rcti *rect);
 void BLI_rctf_init_pt_radius(struct rctf *rect, const float xy[2], float size);
@@ -50,10 +66,19 @@ void BLI_rcti_do_minmax_v(struct rcti *rect, const int xy[2]);
 void BLI_rctf_do_minmax_v(struct rctf *rect, const float xy[2]);
 void BLI_rcti_do_minmax_rcti(struct rcti *rect, const struct rcti *other);
 
+/**
+ * Given 2 rectangles, transform a point from one to another.
+ */
 void BLI_rctf_transform_pt_v(const rctf *dst,
                              const rctf *src,
                              float xy_dst[2],
                              const float xy_src[2]);
+/**
+ * Calculate a 4x4 matrix representing the transformation between two rectangles.
+ *
+ * \note Multiplying a vector by this matrix does *not*
+ * give the same value as #BLI_rctf_transform_pt_v.
+ */
 void BLI_rctf_transform_calc_m4_pivot_min_ex(
     const rctf *dst, const rctf *src, float matrix[4][4], uint x, uint y);
 void BLI_rctf_transform_calc_m4_pivot_min(const rctf *dst, const rctf *src, float matrix[4][4]);
@@ -63,7 +88,13 @@ void BLI_rcti_translate(struct rcti *rect, int x, int y);
 void BLI_rcti_recenter(struct rcti *rect, int x, int y);
 void BLI_rctf_recenter(struct rctf *rect, float x, float y);
 void BLI_rcti_resize(struct rcti *rect, int x, int y);
+/**
+ * Change width & height around the central X location.
+ */
 void BLI_rcti_resize_x(struct rcti *rect, int x);
+/**
+ * Change width & height around the central Y location.
+ */
 void BLI_rcti_resize_y(struct rcti *rect, int y);
 void BLI_rcti_pad(struct rcti *rect, int pad_x, int pad_y);
 void BLI_rctf_pad(struct rctf *rect, float pad_x, float pad_y);
@@ -83,6 +114,14 @@ void BLI_rctf_interp(struct rctf *rect,
 // void BLI_rcti_interp(struct rctf *rect, struct rctf *rect_a, struct rctf *rect_b, float fac);
 bool BLI_rctf_clamp_pt_v(const struct rctf *rect, float xy[2]);
 bool BLI_rcti_clamp_pt_v(const struct rcti *rect, int xy[2]);
+/**
+ * Clamp \a rect within \a rect_bounds, setting \a r_xy to the offset.
+ *
+ * Keeps the top left corner within the bounds, which for user interface
+ * elements is typically where the most important information is.
+ *
+ * \return true if a change is made.
+ */
 bool BLI_rctf_clamp(struct rctf *rect, const struct rctf *rect_bounds, float r_xy[2]);
 bool BLI_rcti_clamp(struct rcti *rect, const struct rcti *rect_bounds, int r_xy[2]);
 bool BLI_rctf_compare(const struct rctf *rect_a, const struct rctf *rect_b, const float limit);
@@ -101,7 +140,13 @@ bool BLI_rctf_isect_x(const rctf *rect, const float x);
 bool BLI_rctf_isect_y(const rctf *rect, const float y);
 bool BLI_rctf_isect_pt(const struct rctf *rect, const float x, const float y);
 bool BLI_rctf_isect_pt_v(const struct rctf *rect, const float xy[2]);
+/**
+ * \returns shortest distance from \a rect to x (0 if inside)
+ */
 int BLI_rcti_length_x(const rcti *rect, const int x);
+/**
+ * \returns shortest distance from \a rect to y (0 if inside)
+ */
 int BLI_rcti_length_y(const rcti *rect, const int y);
 float BLI_rctf_length_x(const rctf *rect, const float x);
 float BLI_rctf_length_y(const rctf *rect, const float y);
@@ -110,6 +155,9 @@ bool BLI_rctf_isect_segment(const struct rctf *rect, const float s1[2], const fl
 bool BLI_rcti_isect_circle(const struct rcti *rect, const float xy[2], const float radius);
 bool BLI_rctf_isect_circle(const struct rctf *rect, const float xy[2], const float radius);
 bool BLI_rcti_inside_rcti(const rcti *rct_a, const rcti *rct_b);
+/**
+ * is \a rct_b inside \a rct_a
+ */
 bool BLI_rctf_inside_rctf(const rctf *rct_a, const rctf *rct_b);
 void BLI_rcti_union(struct rcti *rct_a, const struct rcti *rct_b);
 void BLI_rctf_union(struct rctf *rct_a, const struct rctf *rct_b);
@@ -118,6 +166,9 @@ void BLI_rctf_rcti_copy(struct rctf *dst, const struct rcti *src);
 void BLI_rcti_rctf_copy_floor(struct rcti *dst, const struct rctf *src);
 void BLI_rcti_rctf_copy_round(struct rcti *dst, const struct rctf *src);
 
+/**
+ * Expand the rectangle to fit a rotated \a src.
+ */
 void BLI_rctf_rotate_expand(rctf *dst, const rctf *src, const float angle);
 
 void print_rctf(const char *str, const struct rctf *rect);