[Bf-blender-cvs] [31f31496af6] master: Document some flags controlling BKE_library_foreach_ID_link behavior.

[Bastien Montagne]

Commit: 31f31496af6d343002e6d12a2b5303b0982215c3
Author: Bastien Montagne
Date:   Wed Mar 16 13:14:32 2022 +0100
Branches: master
https://developer.blender.org/rB31f31496af6d343002e6d12a2b5303b0982215c3

Document some flags controlling BKE_library_foreach_ID_link behavior.

===================================================================

M	source/blender/blenkernel/BKE_lib_query.h

===================================================================

diff --git a/source/blender/blenkernel/BKE_lib_query.h b/source/blender/blenkernel/BKE_lib_query.h
index 926be9c7dbe..48cffcf8d2c 100644
--- a/source/blender/blenkernel/BKE_lib_query.h
+++ b/source/blender/blenkernel/BKE_lib_query.h
@@ -115,9 +115,19 @@ typedef int (*LibraryIDLinkCallback)(LibraryIDLinkCallbackData *cb_data);
 /* Flags for the foreach function itself. */
 enum {
   IDWALK_NOP = 0,
+  /** The callback will never modify the ID pointers it processes. */
   IDWALK_READONLY = (1 << 0),
-  IDWALK_RECURSE = (1 << 1),    /* Also implies IDWALK_READONLY. */
-  IDWALK_INCLUDE_UI = (1 << 2), /* Include UI pointers (from WM and screens editors). */
+  /** Recurse into 'descendant' IDs.
+   * Each ID is only processed once. Order of ID processing is not guaranteed.
+   *
+   * Also implies IDWALK_READONLY, and excludes IDWALK_DO_INTERNAL_RUNTIME_POINTERS.
+   *
+   * NOTE: When enabled, embedded IDs are processed separately from their owner, as if they were
+   * regular IDs. Owner ID is not available then in the #LibraryForeachIDData callback data.
+   */
+  IDWALK_RECURSE = (1 << 1),
+  /** Include UI pointers (from WM and screens editors). */
+  IDWALK_INCLUDE_UI = (1 << 2),
   /** Do not process ID pointers inside embedded IDs. Needed by depsgraph processing e.g. */
   IDWALK_IGNORE_EMBEDDED_ID = (1 << 3),