From f69f920164ea7bef3badd36845f4ccd59945e5ee Mon Sep 17 00:00:00 2001 From: Bastien Montagne Date: Tue, 23 Jul 2024 18:20:08 +0200 Subject: [PATCH] Cleanup: BKE Blendfile: Improve PartialWriteContext documentation. --- source/blender/blenkernel/BKE_blendfile.hh | 28 ++++++++++++---------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/source/blender/blenkernel/BKE_blendfile.hh b/source/blender/blenkernel/BKE_blendfile.hh index f7c5f7b010c..215ce00cc79 100644 --- a/source/blender/blenkernel/BKE_blendfile.hh +++ b/source/blender/blenkernel/BKE_blendfile.hh @@ -255,6 +255,9 @@ class PartialWriteContext : NonCopyable, NonMovable { * * WARNING: This also means that dependencies like obdata, shape-keys or actions are not * duplicated either. + * + * NOTE: Either #CLEAR_DEPENDENCIES or #ADD_DEPENDENCIES must be specified in the final + * operation flags for all ID dependencies. This can be achieved by */ CLEAR_DEPENDENCIES = 1 << 8, /** @@ -301,10 +304,13 @@ class PartialWriteContext : NonCopyable, NonMovable { * already exists in the context, it is returned instead of duplicating it again. * * \param options: Control how the added ID (and its dependencies) are handled. See - * #IDAddOptions and #IDAddOperations above for details. - * \param dependencies_filter_cb: Optional, a callback called for each ID usages. Currently, only - * accepted return values are the ones included in - * #MASK_PER_ID_USAGE. + * #IDAddOptions and #IDAddOperations above for details. + * If no #dependencies_filter_cb callback is specified, #options.operations must contain + * either #CLEAR_DEPENDENCIES or #ADD_DEPENDENCIES. + * \param dependencies_filter_cb: Optional, a callback called for each ID usages, which returns + * specific operations flags for each ID usage. + * Currently, only accepted return values are the ones included in #MASK_PER_ID_USAGE. + * Returned flags must always contain either #CLEAR_DEPENDENCIES or #ADD_DEPENDENCIES. * * \return The pointer to the duplicated ID in the partial write context. */ @@ -322,10 +328,9 @@ class PartialWriteContext : NonCopyable, NonMovable { * #matching_uid_map_, and its `session_uid` is not guaranteed to be constant (as it may be * preempted later by another ID added from the current G_MAIN). * - * \param options: Control how the added ID (and its dependencies) are handled. See - * #IDAddOptions and #IDAddOperations above for details, note that only - * relevant operations currently are the #SET_FAKE_USER and #SET_CLIPBOARD_MARK - * ones. + * \param options: Control how the created ID is handled. See #IDAddOptions and #IDAddOperations + * above for details, note that the only relevant operation flags currently are the + * #SET_FAKE_USER and #SET_CLIPBOARD_MARK ones. */ ID *id_create(short id_type, StringRefNull id_name, Library *library, IDAddOptions options); @@ -345,10 +350,9 @@ class PartialWriteContext : NonCopyable, NonMovable { * Remove all unused IDs from the current context. * * \param clear_extra_user: If `true`, the runtime tag ensuring that IDs are written on disk will - * be cleared. In other words, only IDs flagged with 'fake user' and - * their dependencies will be kept. - * Allows to also remove IDs that were added to this context during the - * same editing session, and were not flagged as 'fake user'. + * be cleared. In other words, only IDs flagged with 'fake user' and their dependencies + * will be kept. Allows to also remove IDs that were added to this context during the same + * editing session, and were not flagged as 'fake user'. */ void remove_unused(bool clear_extra_user = false);