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, 22 insertions, 5 deletions

diff --git a/source/blender/blenkernel/BKE_camera.h b/source/blender/blenkernel/BKE_camera.h
index b42fcbe7808..d91b6505672 100644
--- a/source/blender/blenkernel/BKE_camera.h
+++ b/source/blender/blenkernel/BKE_camera.h
@@ -37,22 +37,26 @@ struct Scene;
 struct View3D;
 struct rctf;
 
-/* Camera Datablock */
+/* Camera Data-block */
 
 void *BKE_camera_add(struct Main *bmain, const char *name);
 
 /* Camera Usage */
 
+/**
+ * Get the camera's DOF value, takes the DOF object into account.
+ */
 float BKE_camera_object_dof_distance(struct Object *ob);
 
 int BKE_camera_sensor_fit(int sensor_fit, float sizex, float sizey);
 float BKE_camera_sensor_size(int sensor_fit, float sensor_x, float sensor_y);
 
-/* Camera Parameters:
+/**
+ * Camera Parameters:
  *
  * Intermediate struct for storing camera parameters from various sources,
- * to unify computation of viewplane, window matrix, ... */
-
+ * to unify computation of view-plane, window matrix, ... etc.
+ */
 typedef struct CameraParams {
   /* lens */
   bool is_ortho;
@@ -84,7 +88,7 @@ typedef struct CameraParams {
   float winmat[4][4];
 } CameraParams;
 
-/* values for CameraParams.zoom, need to be taken into account for some operations */
+/* Values for CameraParams.zoom, need to be taken into account for some operations. */
 #define CAMERA_PARAM_ZOOM_INIT_CAMOB 1.0f
 #define CAMERA_PARAM_ZOOM_INIT_PERSP 2.0f
 
@@ -97,6 +101,9 @@ void BKE_camera_params_from_view3d(CameraParams *params,
 
 void BKE_camera_params_compute_viewplane(
     CameraParams *params, int winx, int winy, float aspx, float aspy);
+/**
+ * View-plane is assumed to be already computed.
+ */
 void BKE_camera_params_compute_matrix(CameraParams *params);
 
 /* Camera View Frame */
@@ -114,6 +121,9 @@ void BKE_camera_view_frame(const struct Scene *scene,
                            const struct Camera *camera,
                            float r_vec[4][3]);
 
+/**
+ * \param r_scale: only valid/useful for orthographic cameras.
+ */
 bool BKE_camera_view_frame_fit_to_scene(struct Depsgraph *depsgraph,
                                         const struct Scene *scene,
                                         struct Object *camera_ob,
@@ -128,9 +138,15 @@ bool BKE_camera_view_frame_fit_to_coords(const struct Depsgraph *depsgraph,
 
 /* Camera multi-view API */
 
+/**
+ * Returns the camera to be used for render.
+ */
 struct Object *BKE_camera_multiview_render(const struct Scene *scene,
                                            struct Object *camera,
                                            const char *viewname);
+/**
+ * The view matrix is used by the viewport drawing, it is basically the inverted model matrix.
+ */
 void BKE_camera_multiview_view_matrix(const struct RenderData *rd,
                                       const struct Object *camera,
                                       const bool is_left,
@@ -158,6 +174,7 @@ bool BKE_camera_multiview_spherical_stereo(const struct RenderData *rd,
                                            const struct Object *camera);
 
 /* Camera background image API */
+
 struct CameraBGImage *BKE_camera_background_image_new(struct Camera *cam);
 void BKE_camera_background_image_remove(struct Camera *cam, struct CameraBGImage *bgpic);
 void BKE_camera_background_image_clear(struct Camera *cam);