Cleanup: move doc-strings to declarations

Move into headers or to the top of the function body for internal
implementation details, in some cases remove duplicate doc-strings.
This commit is contained in:
Campbell Barton
2025-04-18 12:52:52 +00:00
parent 54a8ab9a97
commit 3933f45f52
49 changed files with 124 additions and 111 deletions

View File

@@ -93,6 +93,15 @@ void memory_usage_block_alloc(size_t size);
void memory_usage_block_free(size_t size);
size_t memory_usage_block_num(void);
size_t memory_usage_current(void);
/**
* Get the approximate peak memory usage since the last call to #memory_usage_peak_reset.
* This is approximate, because the peak usage is not updated after every allocation (see
* #peak_update_threshold).
*
* In the worst case, the peak memory usage is underestimated by
* `peak_update_threshold * #threads`. After large allocations (larger than the threshold), the
* peak usage is always updated so those allocations will always be taken into account.
*/
size_t memory_usage_peak(void);
void memory_usage_peak_reset(void);

View File

@@ -515,7 +515,8 @@ void MEM_lockfree_printmemlist() {}
void mem_lockfree_clearmemlist() {}
/* unused */
/* Unused. */
void MEM_lockfree_callbackmemlist(void (*func)(void *))
{
(void)func; /* Ignored. */
@@ -560,7 +561,8 @@ uint MEM_lockfree_get_memory_blocks_in_use()
return uint(memory_usage_block_num());
}
/* dummy */
/* Dummy. */
void MEM_lockfree_reset_peak_memory()
{
memory_usage_peak_reset();

View File

@@ -252,15 +252,6 @@ size_t memory_usage_current()
return size_t(mem_in_use);
}
/**
* Get the approximate peak memory usage since the last call to #memory_usage_peak_reset.
* This is approximate, because the peak usage is not updated after every allocation (see
* #peak_update_threshold).
*
* In the worst case, the peak memory usage is underestimated by
* `peak_update_threshold * #threads`. After large allocations (larger than the threshold), the
* peak usage is always updated so those allocations will always be taken into account.
*/
size_t memory_usage_peak()
{
update_global_peak();

View File

@@ -339,6 +339,16 @@ class OCIOImpl : public IOCIOImpl {
void OCIO_PackedImageDescRelease(OCIO_PackedImageDesc *id) override;
bool supportGPUShader() override;
/**
* Setup GPU contexts for a transform defined by processor using GLSL.
* All LUT allocating baking and shader compilation happens here.
*
* Once this function is called, callee could start drawing images
* using regular 2D texture.
*
* When all drawing is finished, gpuDisplayShaderUnbind must be called to
* restore GPU context to its previous state.
*/
bool gpuDisplayShaderBind(OCIO_ConstConfigRcPtr *config,
const char *input,
const char *view,

View File

@@ -711,16 +711,6 @@ static OCIO_GPUDisplayShader &getGPUDisplayShader(
return display_shader;
}
/**
* Setup GPU contexts for a transform defined by processor using GLSL.
* All LUT allocating baking and shader compilation happens here.
*
* Once this function is called, callee could start drawing images
* using regular 2D texture.
*
* When all drawing is finished, gpuDisplayShaderUnbind must be called to
* restore GPU context to its previous state.
*/
bool OCIOImpl::gpuDisplayShaderBind(OCIO_ConstConfigRcPtr *config,
const char *input,
const char *view,

View File

@@ -77,7 +77,13 @@ void RB_dworld_step_simulation(rbDynamicsWorld *world,
/* Export -------------------------- */
/* Exports the dynamics world to physics simulator's serialisation format */
/**
* Exports entire dynamics world to Bullet's "*.bullet" binary format
* which is similar to Blender's SDNA system.
*
* \param world: Dynamics world to write to file
* \param filename: Assumed to be a valid filename, with .bullet extension
*/
void RB_dworld_export(rbDynamicsWorld *world, const char *filename);
/* ********************************** */

View File

@@ -163,6 +163,7 @@ void RB_dworld_delete(rbDynamicsWorld *world)
/* Settings ------------------------- */
/* Gravity */
void RB_dworld_get_gravity(rbDynamicsWorld *world, float g_out[3])
{
copy_v3_btvec3(g_out, world->dynamicsWorld->getGravity());
@@ -174,6 +175,7 @@ void RB_dworld_set_gravity(rbDynamicsWorld *world, const float g_in[3])
}
/* Constraint Solver */
void RB_dworld_set_solver_iterations(rbDynamicsWorld *world, int num_solver_iterations)
{
btContactSolverInfo &info = world->dynamicsWorld->getSolverInfo();
@@ -182,6 +184,7 @@ void RB_dworld_set_solver_iterations(rbDynamicsWorld *world, int num_solver_iter
}
/* Split Impulse */
void RB_dworld_set_split_impulse(rbDynamicsWorld *world, int split_impulse)
{
btContactSolverInfo &info = world->dynamicsWorld->getSolverInfo();
@@ -201,13 +204,6 @@ void RB_dworld_step_simulation(rbDynamicsWorld *world,
/* Export -------------------------- */
/**
* Exports entire dynamics world to Bullet's "*.bullet" binary format
* which is similar to Blender's SDNA system.
*
* \param world: Dynamics world to write to file
* \param filename: Assumed to be a valid filename, with .bullet extension
*/
void RB_dworld_export(rbDynamicsWorld *world, const char *filename)
{
// create a large enough buffer. There is no method to pre-calculate the buffer size yet.

View File

@@ -174,8 +174,6 @@ bool foreach_action_slot_use_with_references(
return true;
}
/* This function has to copy the logic of foreach_action_slot_use_with_references(), as it needs to
* know where exactly those pointers came from. */
bool foreach_action_slot_use_with_rna(ID &animated_id,
FunctionRef<bool(ID &animated_id,
bAction *action,
@@ -183,6 +181,9 @@ bool foreach_action_slot_use_with_rna(ID &animated_id,
PropertyRNA &action_slot_prop,
char *last_slot_identifier)> callback)
{
/* This function has to copy the logic of #foreach_action_slot_use_with_references(),
* as it needs to know where exactly those pointers came from. */
AnimData *adt = BKE_animdata_from_id(&animated_id);
if (adt) {

View File

@@ -171,6 +171,7 @@ static bool animdata_set_action(ReportList *reports, ID *id, bAction **act_slot,
}
/* Tmpact Setter --------------------------------------- */
bool BKE_animdata_set_tmpact(ReportList *reports, ID *id, bAction *act)
{
AnimData *adt = BKE_animdata_from_id(id);
@@ -184,6 +185,7 @@ bool BKE_animdata_set_tmpact(ReportList *reports, ID *id, bAction *act)
}
/* Action Setter --------------------------------------- */
bool BKE_animdata_set_action(ReportList *reports, ID *id, bAction *act)
{
using namespace blender;

View File

@@ -396,6 +396,10 @@ void rotate_eulO(float beul[3], short order, char axis, float angle);
void copy_dq_dq(DualQuat *r, const DualQuat *dq);
void normalize_dq(DualQuat *dq, float totweight);
void add_weighted_dq_dq(DualQuat *dq_sum, const DualQuat *dq, float weight);
/**
* Add the transformation defined by the given dual quaternion to the accumulator,
* using the specified pivot point for combining scale transformations.
*/
void add_weighted_dq_dq_pivot(DualQuat *dq_sum,
const DualQuat *dq,
const float pivot[3],

View File

@@ -13,6 +13,9 @@
/** Quick sort (re-entrant). */
typedef int (*BLI_sort_cmp_t)(const void *a, const void *b, void *ctx);
/**
* Quick sort re-entrant.
*/
void BLI_qsort_r(void *a, size_t n, size_t es, BLI_sort_cmp_t cmp, void *thunk)
#ifdef __GNUC__
__attribute__((nonnull(1, 5)))

View File

@@ -12,6 +12,9 @@
int BLI_cpu_support_sse2(void);
int BLI_cpu_support_sse42(void);
/**
* Write a backtrace into a file for systems which support it.
*/
void BLI_system_backtrace_with_os_info(FILE *fp, const void *os_info);
void BLI_system_backtrace(FILE *fp);

View File

@@ -438,11 +438,6 @@ void *BLI_mempool_calloc(BLI_mempool *pool)
return retval;
}
/**
* Free an element from the mempool.
*
* \note doesn't protect against double frees, take care!
*/
void BLI_mempool_free(BLI_mempool *pool, void *addr)
{
BLI_freenode *newhead = static_cast<BLI_freenode *>(addr);

View File

@@ -2097,20 +2097,16 @@ void add_weighted_dq_dq(DualQuat *dq_sum, const DualQuat *dq, float weight)
}
}
/**
* Add the transformation defined by the given dual quaternion to the accumulator,
* using the specified pivot point for combining scale transformations.
*
* If the resulting dual quaternion would only be used to transform the pivot point itself,
* this function can avoid fully computing the combined scale matrix to get a performance
* boost without affecting the result.
*/
void add_weighted_dq_dq_pivot(DualQuat *dq_sum,
const DualQuat *dq,
const float pivot[3],
const float weight,
const bool compute_scale_matrix)
{
/* NOTE: If the resulting dual quaternion would only be used to transform the pivot point itself,
* this function can avoid fully computing the combined scale matrix to get a performance
* boost without affecting the result. */
/* FIX #32022, #43188, #100373 - bad deformation when combining scaling and rotation. */
if (dq->scale_weight) {
DualQuat mdq = *dq;

View File

@@ -74,9 +74,6 @@ inline char *med3(char *a, char *b, char *c, BLI_sort_cmp_t cmp, void *thunk)
(CMP(thunk, b, c) > 0 ? b : (CMP(thunk, a, c) < 0 ? a : c ));
}
/**
* Quick sort re-entrant.
*/
void BLI_qsort_r(void *a, size_t n, size_t es, BLI_sort_cmp_t cmp, void *thunk)
{
char *pa, *pb, *pc, *pd, *pl, *pm, *pn;

View File

@@ -383,9 +383,6 @@ static void bli_load_symbols()
}
}
/**
* Write a backtrace into a file for systems which support it.
*/
void BLI_system_backtrace_with_os_info(FILE *fp, const void *os_info)
{
const EXCEPTION_POINTERS *exception_info = static_cast<const EXCEPTION_POINTERS *>(os_info);

View File

@@ -145,6 +145,7 @@ extern const BMOpDefine *bmo_opdefines[];
extern const int bmo_opdefines_total;
/*------specific operator helper functions-------*/
void BM_mesh_esubdivide(BMesh *bm,
char edge_hflag,
float smooth,

View File

@@ -1310,7 +1310,6 @@ void bmo_subdivide_edges_exec(BMesh *bm, BMOperator *op)
bm, op, op->slots_out, "geom.out", BM_ALL_NOLOOP, ELE_INNER | ELE_SPLIT | SUBD_SPLIT);
}
/* editmesh-emulating function */
void BM_mesh_esubdivide(BMesh *bm,
const char edge_hflag,
const float smooth,

View File

@@ -28,6 +28,7 @@ namespace blender::compositor {
/* ------------------------------------------------------------------------------------------------
* Denoised Auxiliary Pass Key.
*/
DenoisedAuxiliaryPassKey::DenoisedAuxiliaryPassKey(const DenoisedAuxiliaryPassType type,
const oidn::Quality quality)
: type(type), quality(quality)

View File

@@ -483,8 +483,6 @@ void DepthOfField::resolve_pass_sync()
/** \name Post-FX Rendering.
* \{ */
/* Similar to Film::update_sample_table() but with constant filter radius and constant sample
* count. */
void DepthOfField::update_sample_table()
{
float2 subpixel_offset = inst_.film.pixel_jitter_get();

View File

@@ -82,7 +82,6 @@ void MotionBlurModule::init()
inst_.set_time(time_steps_[1]);
}
/* Runs after rendering a sample. */
void MotionBlurModule::step()
{
if (!enabled_) {

View File

@@ -110,6 +110,7 @@ class MotionBlurModule {
void init();
/* Runs after rendering a sample. */
void step();
void sync();

View File

@@ -334,7 +334,6 @@ void StateSet::execute(RecordingState &recording_state) const
}
}
/* Set state of the GPU module manually. */
void StateSet::set(DRWState state)
{
RecordingState recording_state;

View File

@@ -254,11 +254,12 @@ bool gizmo_window_project_3d(
/** \name RNA Utils
* \{ */
/* Based on 'rna_GizmoProperties_find_operator'. */
wmGizmo *gizmo_find_from_properties(const IDProperty *properties,
const int spacetype,
const int regionid)
{
/* Based on #rna_GizmoProperties_find_operator. */
for (bScreen *screen = static_cast<bScreen *>(G_MAIN->screens.first); screen;
screen = static_cast<bScreen *>(screen->id.next))
{

View File

@@ -208,12 +208,13 @@ int curve_merge_by_distance(const IndexRange points,
return duplicate_count;
}
/* NOTE: The code here is an adapted version of #blender::geometry::point_merge_by_distance. */
blender::bke::CurvesGeometry curves_merge_by_distance(const bke::CurvesGeometry &src_curves,
const float merge_distance,
const IndexMask &selection,
const bke::AttributeFilter &attribute_filter)
{
/* NOTE: The code here is an adapted version of #blender::geometry::point_merge_by_distance. */
const int src_point_size = src_curves.points_num();
if (src_point_size == 0) {
return {};

View File

@@ -53,9 +53,6 @@ int template_search_textbut_height()
return TEMPLATE_SEARCH_TEXTBUT_HEIGHT;
}
/**
* Add a block button for the search menu for templateID and templateSearch.
*/
void template_add_button_search_menu(const bContext *C,
uiLayout *layout,
uiBlock *block,

View File

@@ -48,6 +48,9 @@ static inline void rna_update_cb(bContext *C, void *arg_cb, void * /*arg*/)
/* `interface_template.cc` */
int template_search_textbut_width(PointerRNA *ptr, PropertyRNA *name_prop);
int template_search_textbut_height();
/**
* Add a block button for the search menu for templateID and templateSearch.
*/
void template_add_button_search_menu(const bContext *C,
uiLayout *layout,
uiBlock *block,

View File

@@ -716,9 +716,6 @@ static bool region_poll(const bContext *C,
return region->runtime->type->poll(&params);
}
/**
* \return true if any region polling state changed, and an area re-init is needed.
*/
bool area_regions_poll(bContext *C, const bScreen *screen, ScrArea *area)
{
bScreen *prev_screen = CTX_wm_screen(C);

View File

@@ -158,6 +158,9 @@ bool screen_area_close(bContext *C, ReportList *reports, bScreen *screen, ScrAre
void screen_area_spacelink_add(const Scene *scene, ScrArea *area, eSpace_Type space_type);
AZone *ED_area_actionzone_find_xy(ScrArea *area, const int xy[2]);
/**
* \return true if any region polling state changed, and an area re-init is needed.
*/
bool area_regions_poll(bContext *C, const bScreen *screen, ScrArea *area);
/* `screen_geometry.cc` */

View File

@@ -39,6 +39,13 @@ void do_clay_brush(const Depsgraph &depsgraph,
const Sculpt &sd,
Object &ob,
const IndexMask &node_mask);
/**
* Basic principles of the clay strips brush:
* * Calculate a brush plane from an initial node mask
* * Use this center position and normal to create a brush-local matrix
* * Use this matrix and the plane to calculate and use cube distances for
* * the affected area
*/
void do_clay_strips_brush(const Depsgraph &depsgraph,
const Sculpt &sd,
Object &ob,

View File

@@ -249,13 +249,6 @@ static void calc_bmesh(const Depsgraph &depsgraph,
} // namespace clay_strips_cc
/**
* Basic principles of the clay strips brush:
* * Calculate a brush plane from an initial node mask
* * Use this center position and normal to create a brush-local matrix
* * Use this matrix and the plane to calculate and use cube distances for
* * the affected area
*/
void do_clay_strips_brush(const Depsgraph &depsgraph,
const Sculpt &sd,
Object &object,

View File

@@ -106,6 +106,14 @@ void FILE_OT_start_filter(wmOperatorType *ot);
void FILE_OT_edit_directory_path(wmOperatorType *ot);
void FILE_OT_view_selected(wmOperatorType *ot);
/**
* This callback runs when the user has entered a new path in the file selectors directory field.
*
* Expand & normalize the path then:
* - Change the path when it exists.
* - Prompt the user to create the path if it doesn't
* (providing it passes basic sanity checks).
*/
void file_directory_enter_handle(bContext *C, void *arg_unused, void *arg_but);
void file_filename_enter_handle(bContext *C, void *arg_unused, void *arg_but);

View File

@@ -2890,14 +2890,6 @@ static bool can_create_dir_from_user_input(const char dir[FILE_MAX_LIBEXTRA])
return true;
}
/**
* This callback runs when the user has entered a new path in the file selectors directory field.
*
* Expand & normalize the path then:
* - Change the path when it exists.
* - Prompt the user to create the path if it doesn't
* (providing it passes basic sanity checks).
*/
void file_directory_enter_handle(bContext *C, void * /*arg_unused*/, void * /*arg_but*/)
{
SpaceFile *sfile = CTX_wm_space_file(C);

View File

@@ -903,9 +903,6 @@ void viewops_data_free(bContext *C, ViewOpsData *vod)
/** \name Generic View Operator Utilities
* \{ */
/**
* \param align_to_quat: When not nullptr, set the axis relative to this rotation.
*/
void axis_set_view(bContext *C,
View3D *v3d,
ARegion *region,

View File

@@ -246,6 +246,9 @@ ViewOpsData *viewops_data_create(bContext *C,
const wmEvent *event,
const ViewOpsType *nav_type,
const bool use_cursor_init);
/**
* \param align_to_quat: When not nullptr, set the axis relative to this rotation.
*/
void axis_set_view(bContext *C,
View3D *v3d,
ARegion *region,

View File

@@ -567,7 +567,8 @@ Curve::~Curve()
}
}
/** iterators access */
/* Iterators access. */
Curve::point_iterator Curve::points_begin(float step)
{
vertex_container::iterator second = _Vertices.begin();

View File

@@ -429,7 +429,8 @@ void TVertex::Replace(ViewEdge *iOld, ViewEdge *iNew)
}
}
/** iterators access */
/* Iterators access. */
ViewVertex::edge_iterator TVertex::edges_begin()
{
// return edge_iterator(_FrontEdgeA, _FrontEdgeB, _BackEdgeA, _BackEdgeB, _FrontEdgeA);
@@ -584,7 +585,8 @@ void NonTVertex::AddIncomingViewEdge(ViewEdge *iVEdge)
}
}
/** iterators access */
/* Iterators access. */
ViewVertex::edge_iterator NonTVertex::edges_begin()
{
return edge_iterator(_ViewEdges.begin(), _ViewEdges.end(), _ViewEdges.begin());

View File

@@ -610,7 +610,8 @@ class TVertex : public ViewVertex {
return nullptr;
}
/* iterators access */
/* Iterators access. */
virtual edge_iterator edges_begin();
virtual const_edge_iterator edges_begin() const;
virtual edge_iterator edges_end();
@@ -827,7 +828,8 @@ class NonTVertex : public ViewVertex {
}
}
/* iterators access */
/* Iterators access. */
virtual edge_iterator edges_begin();
virtual const_edge_iterator edges_begin() const;
virtual edge_iterator edges_end();

View File

@@ -516,10 +516,11 @@ static bool sphere_clip_vector(const Vec3r &O, real r, const Vec3r &P, Vec3r &V)
return true;
}
/* TODO: check optimizations:
* use marking ? (measure *timings* ...). */
void compute_curvature_tensor(WVertex *start, real radius, NormalCycle &nc)
{
/* TODO: check optimizations:
* use marking ? (measure *timings* ...). */
// in case we have a non-manifold vertex, skip it...
if (start->isBoundary()) {
return;

View File

@@ -620,10 +620,11 @@ GLuint GLTexture::get_sampler(const GPUSamplerState &sampler_state)
* Dummy texture to see if the implementation supports the requested size.
* \{ */
/* NOTE: This only checks if this mipmap is valid / supported.
* TODO(fclem): make the check cover the whole mipmap chain. */
bool GLTexture::proxy_check(int mip)
{
/* NOTE: This only checks if this mipmap is valid / supported.
* TODO(fclem): make the check cover the whole mipmap chain. */
/* Manual validation first, since some implementation have issues with proxy creation. */
int max_size = GPU_max_texture_size();
int max_3d_size = GPU_max_texture_3d_size();

View File

@@ -314,6 +314,12 @@ enum {
#define FOURCC_DXT4 (DDS_MAKEFOURCC('D', 'X', 'T', '4'))
#define FOURCC_DXT5 (DDS_MAKEFOURCC('D', 'X', 'T', '5'))
/**
* Known image extensions, in most cases these match values
* for images which Blender creates, there are some exceptions to this.
*
* See #BKE_image_path_ext_from_imformat which also stores known extensions.
*/
extern const char *imb_ext_image[];
extern const char *imb_ext_movie[];
extern const char *imb_ext_audio[];

View File

@@ -25,12 +25,6 @@
#define UTIL_DEBUG 0
/**
* Known image extensions, in most cases these match values
* for images which Blender creates, there are some exceptions to this.
*
* See #BKE_image_path_ext_from_imformat which also stores known extensions.
*/
const char *imb_ext_image[] = {
/* #IMB_FTYPE_PNG */
".png",

View File

@@ -534,11 +534,6 @@ BoneExtensionManager::~BoneExtensionManager()
}
}
/**
* BoneExtended is a helper class needed for the Bone chain finder
* See ArmatureImporter::fix_leaf_bones()
* and ArmatureImporter::connect_bone_chains()
*/
BoneExtended::BoneExtended(EditBone *aBone)
{
this->set_name(aBone->name);

View File

@@ -376,6 +376,11 @@ class BoneExtended {
bool has_custom_roll;
public:
/**
* BoneExtended is a helper class needed for the Bone chain finder
* See ArmatureImporter::fix_leaf_bones()
* and ArmatureImporter::connect_bone_chains()
*/
BoneExtended(EditBone *aBone);
void set_name(const char *aName);

View File

@@ -251,15 +251,17 @@ AbstractHierarchyWriter *USDHierarchyIterator::create_particle_writer(
return nullptr;
}
/* Don't generate data writers for instances. */
bool USDHierarchyIterator::include_data_writers(const HierarchyContext *context) const
{
/* Don't generate data writers for instances. */
return !(params_.use_instancing && context->is_instance());
}
/* Don't generate writers for children of instances. */
bool USDHierarchyIterator::include_child_writers(const HierarchyContext *context) const
{
/* Don't generate writers for children of instances. */
return !(params_.use_instancing && context->is_instance());
}

View File

@@ -256,10 +256,6 @@ static bool node_search(bNode *fromnode,
return true;
}
/**
* If the Blender scene has an environment texture,
* export it as a USD dome light.
*/
void world_material_to_dome_light(const USDExportParams &params,
const Scene *scene,
pxr::UsdStageRefPtr stage)

View File

@@ -14,6 +14,10 @@ namespace blender::io::usd {
struct USDExportParams;
struct USDImportParams;
/**
* If the Blender scene has an environment texture,
* export it as a USD dome light.
*/
void world_material_to_dome_light(const USDExportParams &params,
const Scene *scene,
pxr::UsdStageRefPtr stage);

View File

@@ -1904,11 +1904,12 @@ static void rna_def_node_socket_subtypes(BlenderRNA *brna)
rna_def_node_socket_virtual(brna, "NodeSocketVirtual");
}
void rna_def_node_socket_interface_subtypes(BlenderRNA *brna)
{
/* NOTE: interface items are defined outside this file.
* The subtypes must be defined after the base type, so this function
* is called from the interface rna file to ensure correct order. */
void rna_def_node_socket_interface_subtypes(BlenderRNA *brna)
{
for (const bNodeSocketStaticTypeInfo &info : node_socket_subtypes) {
const char *identifier = info.interface_identifier;

View File

@@ -153,9 +153,10 @@ static void strip_unload_font(int fontid)
/** \name Text Effect
* \{ */
/* `data->text[0] == 0` is ignored on purpose in order to make it possible to edit */
bool effects_can_render_text(const Strip *strip)
{
/* `data->text[0] == 0` is ignored on purpose in order to make it possible to edit. */
TextVars *data = static_cast<TextVars *>(strip->effectdata);
if (data->text_size < 1.0f ||
((data->color[3] == 0.0f) &&