Cleanup: doxygen comments
authorCampbell Barton <ideasman42@gmail.com>
Sun, 18 Jun 2017 23:33:23 +0000 (09:33 +1000)
committerCampbell Barton <ideasman42@gmail.com>
Mon, 19 Jun 2017 00:04:30 +0000 (10:04 +1000)
Also remove duplicate & mismatching comments from grease-pencil header.
Keep comments close to implementation to avoid getting out of sync.

22 files changed:
intern/ghost/GHOST_C-api.h
intern/ghost/intern/GHOST_WindowCocoa.h
intern/memutil/MEM_CacheLimiterC-Api.h
source/blender/alembic/intern/abc_exporter.cc
source/blender/alembic/intern/abc_util.h
source/blender/blenkernel/intern/bvhutils.c
source/blender/blenkernel/intern/mesh_evaluate.c
source/blender/blenlib/intern/BLI_ghash.c
source/blender/blenlib/intern/math_geom.c
source/blender/blenlib/intern/math_matrix.c
source/blender/blenlib/intern/string_utf8.c
source/blender/editors/armature/armature_naming.c
source/blender/editors/gpencil/gpencil_intern.h
source/blender/editors/gpencil/gpencil_utils.c
source/blender/editors/space_image/image_ops.c
source/blender/editors/transform/transform_conversions.c
source/blender/editors/transform/transform_snap_object.c
source/blender/freestyle/intern/geometry/matrix_util.h
source/blender/imbuf/IMB_imbuf_types.h
source/blender/python/intern/bpy_rna.c
source/blender/render/intern/source/zbuf.c
source/gameengine/GamePlayer/common/GPC_MouseDevice.h

index 6887063eae9697dd59ef3b6df76d7b254b444a97..967d3f58143ad3f315585533038f3fbbabe5f344 100644 (file)
@@ -43,7 +43,7 @@ extern "C" {
  * Creates a "handle" for a C++ GHOST object.
  * A handle is just an opaque pointer to an empty struct.
  * In the API the pointer is casted to the actual C++ class.
- * \param name Name of the handle to create.
+ * The 'name' argument to the macro is the name of the handle to create.
  */
 
 GHOST_DECLARE_HANDLE(GHOST_SystemHandle);
index b234291396bb999a3c07b8c1b503d2bdce3df6df..5168c48ca2f0233e505b34b8334238395168dc36 100644 (file)
@@ -56,7 +56,7 @@ public:
         * \param systemCocoa           The associated system class to forward events to
         * \param title                         The text shown in the title bar of the window.
         * \param left                          The coordinate of the left edge of the window.
-        * \param top                           The coordinate of the top edge of the window.
+        * \param bottom                        The coordinate of the bottom edge of the window.
         * \param width                         The width the window.
         * \param height                        The height the window.
         * \param state                         The state the window is initially opened with.
index 0fe5469a4d473deab993f7f7a47f9a3d3cb95cf7..b5680890eb89b22ab3bffac4cbe0aa388cada2b7 100644 (file)
@@ -61,8 +61,8 @@ bool MEM_CacheLimiter_is_disabled(void);
  * Create new MEM_CacheLimiter object
  * managed objects are destructed with the data_destructor
  *
- * @param data_destructor
- * @return A new MEM_CacheLimter object
+ * \param data_destructor
+ * \return A new MEM_CacheLimter object
  */
 
 MEM_CacheLimiterC *new_MEM_CacheLimiter(MEM_CacheLimiter_Destruct_Func data_destructor,
@@ -73,7 +73,7 @@ MEM_CacheLimiterC *new_MEM_CacheLimiter(MEM_CacheLimiter_Destruct_Func data_dest
  *
  * Frees the memory of the CacheLimiter but does not touch managed objects!
  *
- * @param This "This" pointer
+ * \param This "This" pointer
  */
 
 void delete_MEM_CacheLimiter(MEM_CacheLimiterC *This);
@@ -81,8 +81,8 @@ void delete_MEM_CacheLimiter(MEM_CacheLimiterC *This);
 /**
  * Manage object
  *
- * @param This "This" pointer, data data object to manage
- * @return CacheLimiterHandle to ref, unref, touch the managed object
+ * \param This "This" pointer, data data object to manage
+ * \return CacheLimiterHandle to ref, unref, touch the managed object
  */
 
 MEM_CacheLimiterHandleC *MEM_CacheLimiter_insert(MEM_CacheLimiterC *This, void *data);
@@ -90,7 +90,7 @@ MEM_CacheLimiterHandleC *MEM_CacheLimiter_insert(MEM_CacheLimiterC *This, void *
 /**
  * Free objects until memory constraints are satisfied
  *
- * @param This "This" pointer
+ * \param This "This" pointer
  */
 
 void MEM_CacheLimiter_enforce_limits(MEM_CacheLimiterC *This);
@@ -99,7 +99,7 @@ void MEM_CacheLimiter_enforce_limits(MEM_CacheLimiterC *This);
  * Unmanage object previously inserted object.
  * Does _not_ delete managed object!
  *
- * @param This "This" pointer, handle of object
+ * \param handle of object
  */
 
 void MEM_CacheLimiter_unmanage(MEM_CacheLimiterHandleC *handle);
@@ -108,7 +108,7 @@ void MEM_CacheLimiter_unmanage(MEM_CacheLimiterHandleC *handle);
 /**
  * Raise priority of object (put it at the tail of the deletion chain)
  *
- * @param handle of object
+ * \param handle of object
  */
 
 void MEM_CacheLimiter_touch(MEM_CacheLimiterHandleC *handle);
@@ -117,7 +117,7 @@ void MEM_CacheLimiter_touch(MEM_CacheLimiterHandleC *handle);
  * Increment reference counter. Objects with reference counter != 0 are _not_
  * deleted.
  *
- * @param handle of object
+ * \param handle of object
  */
 
 void MEM_CacheLimiter_ref(MEM_CacheLimiterHandleC *handle);
@@ -126,7 +126,7 @@ void MEM_CacheLimiter_ref(MEM_CacheLimiterHandleC *handle);
  * Decrement reference counter. Objects with reference counter != 0 are _not_
  * deleted.
  *
- * @param handle of object
+ * \param handle of object
  */
 
 void MEM_CacheLimiter_unref(MEM_CacheLimiterHandleC *handle);
@@ -134,7 +134,7 @@ void MEM_CacheLimiter_unref(MEM_CacheLimiterHandleC *handle);
 /**
  * Get reference counter.
  *
- * @param handle of object
+ * \param handle of object
  */
 
 int MEM_CacheLimiter_get_refcount(MEM_CacheLimiterHandleC *handle);
@@ -142,7 +142,7 @@ int MEM_CacheLimiter_get_refcount(MEM_CacheLimiterHandleC *handle);
 /**
  * Get pointer to managed object
  *
- * @param handle of object
+ * \param handle of object
  */
 
 void *MEM_CacheLimiter_get(MEM_CacheLimiterHandleC *handle);
index 3f359990980a745e335d2f0bbbdcf0ed8ef24e92..4fe65b96f3655c3fce18f7bb3887c943c60a0b77 100644 (file)
@@ -131,13 +131,12 @@ static bool object_type_is_exportable(Object *ob)
 /**
  * Returns whether this object should be exported into the Alembic file.
  *
- * @param settings export settings, used for options like 'selected only'.
- * @param ob the object in question.
- * @param is_duplicated normally false; true when the object is instanced
- *                      into the scene by a dupli-object (e.g. part of a
- *                      dupligroup). This ignores selection and layer
- *                      visibility, and assumes that the dupli-object itself
- *                      (e.g. the group-instantiating empty) is exported.
+ * \param settings: export settings, used for options like 'selected only'.
+ * \param ob: the object in question.
+ * \param is_duplicated: Normally false; true when the object is instanced
+ * into the scene by a dupli-object (e.g. part of a dupligroup).
+ * This ignores selection and layer visibility,
+ * and assumes that the dupli-object itself (e.g. the group-instantiating empty) is exported.
  */
 static bool export_object(const ExportSettings * const settings, Object *ob,
                           bool is_duplicated)
index 74d0faf97d37cdacbaff07666cdfce96f24ff3a7..2526958111acd3944a3f42276f08f2aa73ee8f08 100644 (file)
@@ -33,7 +33,7 @@
 #endif
 
 /**
- * @brief The CacheReader struct is only used for anonymous pointers,
+ * \brief The CacheReader struct is only used for anonymous pointers,
  * to interface between C and C++ code. This library only creates
  * pointers to AbcObjectReader (or subclasses thereof).
  */
index c0e4ef37a93f0a92a92ddd2be95b67f2304ca301..c1fad4f80c83c68ee136c4212c1de47596809f08 100644 (file)
@@ -917,10 +917,10 @@ BVHTree *bvhtree_from_mesh_faces(
 
 /**
  * Builds a bvh tree where nodes are the given tessellated faces (note: does not copy given mfaces!).
- * \param vert_allocated if true, vert freeing will be done when freeing data.
- * \param face_allocated if true, face freeing will be done when freeing data.
+ * \param vert_allocated: if true, vert freeing will be done when freeing data.
+ * \param face_allocated: if true, face freeing will be done when freeing data.
  * \param faces_mask: if not null, true elements give which faces to add to BVH tree.
- * \param numFaces_active if >= 0, number of active faces to add to BVH tree (else will be computed from mask).
+ * \param faces_num_active: if >= 0, number of active faces to add to BVH tree (else will be computed from mask).
  */
 BVHTree *bvhtree_from_mesh_faces_ex(
         BVHTreeFromMesh *data, const MVert *vert, const bool vert_allocated,
index 37f4477febf5ef16aadd26dbf192f714ba89fe28..5dfcef9f9bf3ba82c2990d728880460a9ab82747 100644 (file)
@@ -1629,8 +1629,8 @@ void BKE_mesh_normals_loop_custom_from_vertices_set(
 /**
  * Computes average per-vertex normals from given custom loop normals.
  *
- * @param clnors The computed custom loop normals.
- * @param r_vert_clnors The (already allocated) array where to store averaged per-vertex normals.
+ * \param clnors: The computed custom loop normals.
+ * \param r_vert_clnors: The (already allocated) array where to store averaged per-vertex normals.
  */
 void BKE_mesh_normals_loop_to_vertex(
         const int numVerts, const MLoop *mloops, const int numLoops,
index d1fe3557801bcc925ccca0a5a6d46b813457400b..69dee12c713ddad9f77659d12dd9f52ebfb1273e 100644 (file)
@@ -116,6 +116,12 @@ struct GHash {
 };
 
 
+/* -------------------------------------------------------------------- */
+/* GHash API */
+
+/** \name Internal Utility API
+ * \{ */
+
 BLI_INLINE void ghash_entry_copy(
         GHash *gh_dst, Entry *dst, GHash *gh_src, Entry *src,
         GHashKeyCopyFP keycopyfp, GHashValCopyFP valcopyfp)
@@ -132,12 +138,6 @@ BLI_INLINE void ghash_entry_copy(
        }
 }
 
-/* -------------------------------------------------------------------- */
-/* GHash API */
-
-/** \name Internal Utility API
- * \{ */
-
 /**
  * Get the full hash for a key.
  */
index e28f4902c140ec726a27f894c21774ebf93b46d9..bfe1aefcbbd9538f8da6f118be0fce63e81d4c8c 100644 (file)
@@ -572,8 +572,8 @@ float dist_squared_to_ray_v3(
 }
 /**
  * Find the closest point in a seg to a ray and return the distance squared.
- * \param r_point : Is the point on segment closest to ray (or to ray_origin if the ray and the segment are parallel).
- * \param depth: the distance of r_point projection on ray to the ray_origin.
+ * \param r_point: Is the point on segment closest to ray (or to ray_origin if the ray and the segment are parallel).
+ * \param r_depth: the distance of r_point projection on ray to the ray_origin.
  */
 float dist_squared_ray_to_seg_v3(
         const float ray_origin[3], const float ray_direction[3],
index 9a60c670ec7a4e0909fde47dbdeb58d2720e109a..f47f9ad76e65bfef274744f57af43ebbf393fb4b 100644 (file)
@@ -1738,16 +1738,16 @@ void blend_m4_m4m4(float out[4][4], float dst[4][4], float src[4][4], const floa
 /**
  * A polar-decomposition-based interpolation between matrix A and matrix B.
  *
- * \note This code is about five times slower as the 'naive' interpolation done by \a blend_m3_m3m3
- *       (it typically remains below 2 usec on an average i74700, while \a blend_m3_m3m3 remains below 0.4 usec).
+ * \note This code is about five times slower as the 'naive' interpolation done by #blend_m3_m3m3
+ *       (it typically remains below 2 usec on an average i74700, while #blend_m3_m3m3 remains below 0.4 usec).
  *       However, it gives expected results even with non-uniformaly scaled matrices, see T46418 for an example.
  *
  * Based on "Matrix Animation and Polar Decomposition", by Ken Shoemake & Tom Duff
  *
- * @return R the interpolated matrix.
- * @param A the intput matrix which is totally effective with \a t = 0.0.
- * @param B the intput matrix which is totally effective with \a t = 1.0.
- * @param t the interpolation factor.
+ * \param R: Resulting interpolated matrix.
+ * \param A: Input matrix which is totally effective with `t = 0.0`.
+ * \param B: Input matrix which is totally effective with `t = 1.0`.
+ * \param t: Interpolation factor.
  */
 void interp_m3_m3m3(float R[3][3], float A[3][3], float B[3][3], const float t)
 {
@@ -1777,12 +1777,12 @@ void interp_m3_m3m3(float R[3][3], float A[3][3], float B[3][3], const float t)
 }
 
 /**
- * Complete transform matrix interpolation, based on polar-decomposition-based interpolation from interp_m3_m3m3.
+ * Complete transform matrix interpolation, based on polar-decomposition-based interpolation from #interp_m3_m3m3.
  *
- * @return R the interpolated matrix.
- * @param A the intput matrix which is totally effective with \a t = 0.0.
- * @param B the intput matrix which is totally effective with \a t = 1.0.
- * @param t the interpolation factor.
+ * \param R: Resulting interpolated matrix.
+ * \param A: Input matrix which is totally effective with `t = 0.0`.
+ * \param B: Input matrix which is totally effective with `t = 1.0`.
+ * \param t: Interpolation factor.
  */
 void interp_m4_m4m4(float R[4][4], float A[4][4], float B[4][4], const float t)
 {
index b7e5e3e101ed5fd908a06967155f7699a99d5eb1..229a97a2fa7bd5652b13f1a3c39ab61cf2071aee 100644 (file)
@@ -167,7 +167,7 @@ utf8_error:
 /**
  * Remove any invalid utf-8 byte (taking into account multi-bytes sequence of course).
  *
- * @return number of stripped bytes.
+ * \return number of stripped bytes.
  */
 int BLI_utf8_invalid_strip(char *str, size_t length)
 {
index c928508237da5b3bc16b6082a6ce5accee99bd3f..db4b642fe9100a99d8f1d86d285aae86de6ca57f 100644 (file)
@@ -311,8 +311,8 @@ typedef struct BoneFlipNameData {
  * This way if we are flipping related bones (e.g., Bone.L, Bone.R) at the same time
  * all the bones are safely renamed, without conflicting with each other.
  *
- * \param arm Armature the bones belong to
- * \param bones ListBase of BoneConflict elems, populated via ED_armature_bones_flip_names_add
+ * \param arm: Armature the bones belong to
+ * \param bones_names: List of BoneConflict elems.
  */
 void ED_armature_bones_flip_names(bArmature *arm, ListBase *bones_names)
 {
index 13af06fd4fdcefcc6ec09fec130e380d60e1f31e..a3734c56c596c8d6021162277d519c1fe70aee29 100644 (file)
@@ -71,75 +71,23 @@ typedef struct GP_SpaceConversion {
        float mat[4][4];     /* transform matrix on the strokes (introduced in [b770964]) */
 } GP_SpaceConversion;
 
-
-/**
- * Check whether a given stroke segment is inside a circular brush
- *
- * \param mval     The current screen-space coordinates (midpoint) of the brush
- * \param mvalo    The previous screen-space coordinates (midpoint) of the brush (NOT CURRENTLY USED)
- * \param rad      The radius of the brush
- *
- * \param x0, y0   The screen-space x and y coordinates of the start of the stroke segment
- * \param x1, y1   The screen-space x and y coordinates of the end of the stroke segment
- */
 bool gp_stroke_inside_circle(const int mval[2], const int UNUSED(mvalo[2]),
                              int rad, int x0, int y0, int x1, int y1);
 
-
-/**
- * Init settings for stroke point space conversions
- *
- * \param[out] r_gsc  The space conversion settings struct, populated with necessary params
- */
 void gp_point_conversion_init(struct bContext *C, GP_SpaceConversion *r_gsc);
 
-/**
- * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D)
- *
- * \param[out] r_x  The screen-space x-coordinate of the point
- * \param[out] r_y  The screen-space y-coordinate of the point
- */
 void gp_point_to_xy(GP_SpaceConversion *settings, struct bGPDstroke *gps, struct bGPDspoint *pt,
                     int *r_x, int *r_y);
 
-/**
- * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D)
- *
- * Just like gp_point_to_xy(), except the resulting coordinates are floats not ints.
- * Use this version to solve "stair-step" artifacts which may arise when roundtripping the calculations.
- *
- * \param[out] r_x  The screen-space x-coordinate of the point
- * \param[out] r_y  The screen-space y-coordinate of the point
- */
 void gp_point_to_xy_fl(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt,
                        float *r_x, float *r_y);
 
-/**
- * Convert point to parent space
- *
- * \param pt         Original point
- * \param diff_mat   Matrix with the difference between original parent matrix
- * \param[out] r_pt  Pointer to new point after apply matrix
- */
 void gp_point_to_parent_space(bGPDspoint *pt, float diff_mat[4][4], bGPDspoint *r_pt);
-/**
- * Change points position relative to parent object
- */
+
 void gp_apply_parent(bGPDlayer *gpl, bGPDstroke *gps);
-/**
- * Change point position relative to parent object
- */
+
 void gp_apply_parent_point(bGPDlayer *gpl, bGPDspoint *pt);
 
-/**
- * Convert a screenspace point to a 3D Grease Pencil coordinate.
- *
- * For use with editing tools where it is easier to perform the operations in 2D,
- * and then later convert the transformed points back to 3D.
- *
- * \param screeN_co    The screenspace 2D coordinates to convert to 
- * \param[out] r_out  The resulting 3D coordinates of the input point
- */
 bool gp_point_xy_to_3d(GP_SpaceConversion *gsc, struct Scene *scene, const float screen_co[2], float r_out[3]);
 
 /* Poll Callbacks ------------------------------------ */
@@ -165,43 +113,10 @@ struct GHash *gp_copybuf_validate_colormap(bGPdata *gpd);
 void gp_stroke_delete_tagged_points(bGPDframe *gpf, bGPDstroke *gps, bGPDstroke *next_stroke, int tag_flags);
 
 
-/**
- * Apply smooth to stroke point 
- * \param gps              Stroke to smooth
- * \param i                Point index
- * \param inf              Amount of smoothing to apply
- * \param affect_pressure  Apply smoothing to pressure values too?
- */
 bool gp_smooth_stroke(bGPDstroke *gps, int i, float inf, bool affect_pressure);
-
-/**
-* Apply smooth for strength to stroke point
-* \param gps              Stroke to smooth
-* \param i                Point index
-* \param inf              Amount of smoothing to apply
-*/
 bool gp_smooth_stroke_strength(bGPDstroke *gps, int i, float inf);
-
-/**
-* Apply smooth for thickness to stroke point (use pressure)
-* \param gps              Stroke to smooth
-* \param i                Point index
-* \param inf              Amount of smoothing to apply
-*/
 bool gp_smooth_stroke_thickness(bGPDstroke *gps, int i, float inf);
-
-/**
- * Subdivide a stroke once, by adding points at the midpoint between each pair of points
- * \param gps           Stroke data
- * \param new_totpoints Total number of points (after subdividing)
- */
 void gp_subdivide_stroke(bGPDstroke *gps, const int new_totpoints);
-
-/**
-* Add randomness to stroke
-* \param gps           Stroke data
-* \param brush         Brush data
-*/
 void gp_randomize_stroke(bGPDstroke *gps, bGPDbrush *brush);
 
 /* Layers Enums -------------------------------------- */
index 2b662d04f0383be23acbc0f1e796acb083fac8e8..ed05b8be9ca85f49f9686075e136b610af9d478d 100644 (file)
@@ -391,7 +391,16 @@ EnumPropertyItem *ED_gpencil_layers_with_new_enum_itemf(bContext *C, PointerRNA
 /* ******************************************************** */
 /* Brush Tool Core */
 
-/* Check if part of stroke occurs within last segment drawn by eraser */
+/**
+ * Check whether a given stroke segment is inside a circular brush
+ *
+ * \param mval     The current screen-space coordinates (midpoint) of the brush
+ * \param mvalo    The previous screen-space coordinates (midpoint) of the brush (NOT CURRENTLY USED)
+ * \param rad      The radius of the brush
+ *
+ * \param x0, y0   The screen-space x and y coordinates of the start of the stroke segment
+ * \param x1, y1   The screen-space x and y coordinates of the end of the stroke segment
+ */
 bool gp_stroke_inside_circle(const int mval[2], const int UNUSED(mvalo[2]),
                              int rad, int x0, int y0, int x1, int y1)
 {
@@ -502,7 +511,11 @@ bGPDpalettecolor *ED_gpencil_stroke_getcolor(bGPdata *gpd, bGPDstroke *gps)
 /* ******************************************************** */
 /* Space Conversion */
 
-/* Init handling for space-conversion function (from passed-in parameters) */
+/**
+ * Init settings for stroke point space conversions
+ *
+ * \param r_gsc: [out] The space conversion settings struct, populated with necessary params
+ */
 void gp_point_conversion_init(bContext *C, GP_SpaceConversion *r_gsc)
 {
        ScrArea *sa = CTX_wm_area(C);
@@ -538,7 +551,13 @@ void gp_point_conversion_init(bContext *C, GP_SpaceConversion *r_gsc)
        }
 }
 
-/* convert point to parent space */
+/**
+ * Convert point to parent space
+ *
+ * \param pt         Original point
+ * \param diff_mat   Matrix with the difference between original parent matrix
+ * \param[out] r_pt  Pointer to new point after apply matrix
+ */
 void gp_point_to_parent_space(bGPDspoint *pt, float diff_mat[4][4], bGPDspoint *r_pt) 
 {
        float fpt[3];
@@ -547,7 +566,9 @@ void gp_point_to_parent_space(bGPDspoint *pt, float diff_mat[4][4], bGPDspoint *
        copy_v3_v3(&r_pt->x, fpt);
 }
 
-/* Change position relative to parent object */
+/**
+ * Change points position relative to parent object
+ */
 void gp_apply_parent(bGPDlayer *gpl, bGPDstroke *gps)
 {
        bGPDspoint *pt;
@@ -568,7 +589,9 @@ void gp_apply_parent(bGPDlayer *gpl, bGPDstroke *gps)
        }
 }
 
-/* Change point position relative to parent object */
+/**
+ * Change point position relative to parent object
+ */
 void gp_apply_parent_point(bGPDlayer *gpl, bGPDspoint *pt)
 {
        /* undo matrix */
@@ -583,8 +606,13 @@ void gp_apply_parent_point(bGPDlayer *gpl, bGPDspoint *pt)
        copy_v3_v3(&pt->x, fpt);
 }
 
-/* Convert Grease Pencil points to screen-space values
- * WARNING: This assumes that the caller has already checked whether the stroke in question can be drawn
+/**
+ * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D)
+ *
+ * \param[out] r_x  The screen-space x-coordinate of the point
+ * \param[out] r_y  The screen-space y-coordinate of the point
+ *
+ * \warning This assumes that the caller has already checked whether the stroke in question can be drawn.
  */
 void gp_point_to_xy(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt,
                     int *r_x, int *r_y)
@@ -628,8 +656,16 @@ void gp_point_to_xy(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt,
        }
 }
 
-/* Convert Grease Pencil points to screen-space values (as floats)
- * WARNING: This assumes that the caller has already checked whether the stroke in question can be drawn
+/**
+ * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D)
+ *
+ * Just like gp_point_to_xy(), except the resulting coordinates are floats not ints.
+ * Use this version to solve "stair-step" artifacts which may arise when roundtripping the calculations.
+ *
+ * \param r_x: [out] The screen-space x-coordinate of the point
+ * \param r_y: [out] The screen-space y-coordinate of the point
+ *
+ * \warning This assumes that the caller has already checked whether the stroke in question can be drawn
  */
 void gp_point_to_xy_fl(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt,
                        float *r_x, float *r_y)
@@ -688,6 +724,12 @@ void gp_point_to_xy_fl(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt,
 /**
  * Project screenspace coordinates to 3D-space
  *
+ * For use with editing tools where it is easier to perform the operations in 2D,
+ * and then later convert the transformed points back to 3D.
+ *
+ * \param screen_co: The screenspace 2D coordinates to convert to
+ * \param r_out: The resulting 3D coordinates of the input point
+ *
  * \note We include this as a utility function, since the standard method
  * involves quite a few steps, which are invariably always the same
  * for all GPencil operations. So, it's nicer to just centralize these.
@@ -722,7 +764,7 @@ bool gp_point_xy_to_3d(GP_SpaceConversion *gsc, Scene *scene, const float screen
 }
 
 /**
- * Apply smooth to stroke point 
+ * Apply smooth to stroke point
  * \param gps              Stroke to smooth
  * \param i                Point index
  * \param inf              Amount of smoothing to apply
index c2cfca295a47b04c0cedb770594ab4959b3c14ff..501a5a358997bc68d83e6d5103447e06b0b1923d 100644 (file)
@@ -1067,6 +1067,7 @@ typedef struct ImageOpenData {
 typedef struct ImageFrameRange {
        struct ImageFrameRange *next, *prev;
        ListBase frames;
+       /**  The full path of the first file in the list of image files */
        char filepath[FILE_MAX];
 } ImageFrameRange;
 
@@ -1092,8 +1093,7 @@ static void image_open_cancel(bContext *UNUSED(C), wmOperator *op)
 /**
  * \brief Get a list of frames from the list of image files matching the first file name sequence pattern
  * \param ptr [in] the RNA pointer containing the "directory" entry and "files" collection
- * \param frames [out] the list of frame numbers found in the files matching the first one by name
- * \param path [out] the full path of the first file in the list of image files
+ * \param frames_all [out] the list of frame numbers found in the files matching the first one by name
  */
 static void image_sequence_get_frame_ranges(PointerRNA *ptr, ListBase *frames_all)
 {
index dabce262125788269c7b6f9f3a596f4d424e0bde..ba474e93b70dbfa357e9cdeaaf112787a7a57678 100644 (file)
@@ -2008,9 +2008,9 @@ static bool bmesh_test_dist_add(
 }
 
 /**
- * \parm mtx: Measure disatnce in this space.
- * \parm dists: Store the closest connected distance to selected vertices.
- * \parm index: Optionally store the original index we're measuring the distance to (can be NULL).
+ * \param mtx: Measure disatnce in this space.
+ * \param dists: Store the closest connected distance to selected vertices.
+ * \param index: Optionally store the original index we're measuring the distance to (can be NULL).
  */
 static void editmesh_set_connectivity_distance(BMesh *bm, float mtx[3][3], float *dists, int *index)
 {
index b33528b4149c2cc8ddd02c2dcdfdef00f007e143..aecd24d4e4092cb7c417d45952fb038ff4969e43 100644 (file)
@@ -234,7 +234,7 @@ static void raycast_all_cb(void *userdata, int index, const BVHTreeRay *ray, BVH
 
 /* -------------------------------------------------------------------- */
 
-/** \Common utilities
+/** Common utilities
  * \{ */
 
 /**
@@ -620,7 +620,7 @@ static float dist_aabb_to_plane(
 
 /* -------------------------------------------------------------------- */
 
-/** \Walk DFS
+/** Walk DFS
  * \{ */
 
 typedef void (*Nearest2DGetEdgeVertsCallback)(const int index, const float *v_pair[2], void *data);
index d65b0ea803b6413454fc44a1da8a98d3f2ac773d..444fd7c478584dd0c3d2e3a14e8eba1d50fe9f32 100644 (file)
@@ -50,15 +50,15 @@ namespace MatrixUtil {
        /**
         * computes the eigen values and eigen vectors of a semi definite symmetric matrix
         *
-        * @param  matrix is stored in column symmetric storage, i.e.
+        * \param  mat: The matrix stored in column symmetric storage, i.e.
         *     matrix = { m11, m12, m22, m13, m23, m33, m14, m24, m34, m44 ... }
         *     size = n(n+1)/2
         *
-        * @param eigen_vectors (return) = { v1, v2, v3, ..., vn } 
+        * \param eigen_vec: (return) = { v1, v2, v3, ..., vn }
         *   where vk = vk0, vk1, ..., vkn
         *     size = n^2, must be allocated by caller
         *
-        * @param eigen_values  (return) are in decreasing order
+        * \param eigen_val: (return) are in decreasing order
         *     size = n,   must be allocated by caller
         */
        void semi_definite_symmetric_eigen(const double *mat, int n, double *eigen_vec, double *eigen_val);
index f4b2539d7d78d874458a6ccce1eec9170e42e18c..1701c2ba307dab53699e5dfbd7b1ba27559c4610 100644 (file)
@@ -237,9 +237,8 @@ typedef struct ImBuf {
 /**
  * \name Imbuf Component flags
  * \brief These flags determine the components of an ImBuf struct.
- */
-/**@{*/
-/** \brief Flag defining the components of the ImBuf struct. */
+ *
+ * \{ */
 
 #define IB_rect                                (1 << 0)
 #define IB_test                                (1 << 1)
@@ -259,15 +258,20 @@ typedef struct ImBuf {
 #define IB_thumbnail           (1 << 15)
 #define IB_multiview           (1 << 16)
 
+/** \} */
+
 /**
  * \name Imbuf preset profile tags
  * \brief Some predefined color space profiles that 8 bit imbufs can represent
- */
+ *
+ * \{ */
 #define IB_PROFILE_NONE                        0
 #define IB_PROFILE_LINEAR_RGB  1
 #define IB_PROFILE_SRGB                        2
 #define IB_PROFILE_CUSTOM              3
 
+/** \} */
+
 /* dds */
 #ifdef WITH_DDS
 #ifndef DDS_MAKEFOURCC
@@ -298,8 +302,16 @@ extern const char *imb_ext_audio[];
 /* image formats that can only be loaded via filepath */
 extern const char *imb_ext_image_filepath_only[];
 
+/**
+ * \name Imbuf Color Management Flag
+ * \brief Used with #ImBuf.colormanage_flag
+ *
+ * \{ */
+
 enum {
        IMB_COLORMANAGE_IS_DATA = (1 << 0)
 };
 
-#endif
+/** \} */
+
+#endif  /* __IMB_IMBUF_TYPES_H__ */
index cfbb4ccdc3843fdf05e9ff0c63625c1d609b5cc9..eda880d4dceb2452f31cc854cb3265152fdbaddb 100644 (file)
@@ -7345,7 +7345,7 @@ static int bpy_class_validate_recursive(PointerRNA *dummyptr, StructRNA *srna, v
                                arg_count = ((PyCodeObject *)PyFunction_GET_CODE(item))->co_argcount;
 
                                /* note, the number of args we check for and the number of args we give to
-                                * @staticmethods are different (quirk of python),
+                                * '@staticmethods' are different (quirk of python),
                                 * this is why rna_function_arg_count() doesn't return the value -1*/
                                if (is_staticmethod) {
                                        func_arg_count++;
index e497ec1a8702cd9d28cfae3e619b23cc1bbfdd38..68707f163afc294eef2a8c72ceda259207a7d92f 100644 (file)
@@ -1601,7 +1601,6 @@ void zspan_scanconvert(ZSpan *zspan, void *handle, float *v1, float *v2, float *
  * Note: uses globals.
  * \param v1 start coordinate s
  * \param v2 target coordinate t
- * \param b1 
  * \param b2 
  * \param b3
  * \param a index for coordinate (x, y, or z)
index 504df2376bb88ebbbcb307c3a3966705f24d6a96..2492219772339a50be7882cb40449916c075c4c9 100644 (file)
@@ -67,8 +67,6 @@ public:
         * Call this routine to update the mouse device when a button state changes.
         * \param button        Which button state changes.
         * \param isDown        The new state of the button.
-        * \param x                     Position x-coordinate of the cursor at the time of the state change.
-        * \param y                     Position y-coordinate of the cursor at the time of the state change.
         * \return Indication as to whether the event was processed.
         */
        virtual bool ConvertButtonEvent(TButtonId button, bool isDown);