Cleanup: comments (long lines) in blenkernel

1 files changed, 97 insertions, 61 deletions

diff --git a/source/blender/blenkernel/intern/library.c b/source/blender/blenkernel/intern/library.c
index ca73415b962..ad0c405ab28 100644
--- a/source/blender/blenkernel/intern/library.c
+++ b/source/blender/blenkernel/intern/library.c
@@ -170,11 +170,14 @@ void id_lib_extern(ID *id)
   }
 }
 
-/* ensure we have a real user */
-/* Note: Now that we have flags, we could get rid of the 'fake_user' special case, flags are enough to ensure
- *       we always have a real user.
- *       However, ID_REAL_USERS is used in several places outside of core library.c, so think we can wait later
- *       to make this change... */
+/**
+ * Ensure we have a real user
+ *
+ * \note Now that we have flags, we could get rid of the 'fake_user' special case,
+ * flags are enough to ensure we always have a real user.
+ * However, #ID_REAL_USERS is used in several places outside of core library.c,
+ * so think we can wait later to make this change.
+ */
 void id_us_ensure_real(ID *id)
 {
   if (id) {
@@ -254,7 +257,8 @@ void id_us_min(ID *id)
     }
 
     if ((id->us == limit) && (id->tag & LIB_TAG_EXTRAUSER)) {
-      /* We need an extra user here, but never actually incremented user count for it so far, do it now. */
+      /* We need an extra user here, but never actually incremented user count for it so far,
+       * do it now. */
       id_us_ensure_real(id);
     }
   }
@@ -293,7 +297,8 @@ static int id_expand_local_callback(void *UNUSED(user_data),
     return IDWALK_RET_NOP;
   }
 
-  /* Can happen that we get unlinkable ID here, e.g. with shapekey referring to itself (through drivers)...
+  /* Can happen that we get un-linkable ID here, e.g. with shape-key referring to itself
+   * (through drivers)...
    * Just skip it, shape key can only be either indirectly linked, or fully local, period.
    * And let's curse one more time that stupid useless shapekey ID type! */
   if (*id_pointer && *id_pointer != id_self && BKE_idcode_is_linkable(GS((*id_pointer)->name))) {
@@ -304,7 +309,8 @@ static int id_expand_local_callback(void *UNUSED(user_data),
 }
 
 /**
- * Expand ID usages of given id as 'extern' (and no more indirect) linked data. Used by ID copy/make_local functions.
+ * Expand ID usages of given id as 'extern' (and no more indirect) linked data.
+ * Used by ID copy/make_local functions.
  */
 void BKE_id_expand_local(Main *bmain, ID *id)
 {
@@ -335,7 +341,8 @@ void BKE_id_make_local_generic(Main *bmain,
   /* - only lib users: do nothing (unless force_local is set)
    * - only local users: set flag
    * - mixed: make copy
-   * In case we make a whole lib's content local, we always want to localize, and we skip remapping (done later).
+   * In case we make a whole lib's content local,
+   * we always want to localize, and we skip remapping (done later).
    */
 
   if (!ID_IS_LINKED(id)) {
@@ -352,7 +359,8 @@ void BKE_id_make_local_generic(Main *bmain,
     else {
       ID *id_new;
 
-      /* Should not fail in expected usecases, but a few ID types cannot be copied (LIB, WM, SCR...). */
+      /* Should not fail in expected use cases,
+       * but a few ID types cannot be copied (LIB, WM, SCR...). */
       if (BKE_id_copy(bmain, id, &id_new)) {
         id_new->us = 0;
 
@@ -380,13 +388,15 @@ void BKE_id_make_local_generic(Main *bmain,
  *
  * \note Always set ID->newid pointer in case it gets duplicated...
  *
- * \param lib_local: Special flag used when making a whole library's content local, it needs specific handling.
+ * \param lib_local: Special flag used when making a whole library's content local,
+ * it needs specific handling.
  *
  * \return true if the block can be made local.
  */
 bool id_make_local(Main *bmain, ID *id, const bool test, const bool lib_local)
 {
-  /* We don't care whether ID is directly or indirectly linked in case we are making a whole lib local... */
+  /* We don't care whether ID is directly or indirectly linked
+   * in case we are making a whole lib local... */
   if (!lib_local && (id->tag & LIB_TAG_INDIRECT)) {
     return false;
   }
@@ -601,15 +611,18 @@ bool BKE_id_copy_is_allowed(const ID *id)
 /**
  * Generic entry point for copying a datablock (new API).
  *
- * \note Copy is only affecting given data-block (no ID used by copied one will be affected, besides usercount).
- *       There is only one exception, if LIB_ID_COPY_ACTIONS is defined, actions used by animdata will be duplicated.
+ * \note Copy is only affecting given data-block
+ * (no ID used by copied one will be affected, besides usercount).
+ * There is only one exception, if #LIB_ID_COPY_ACTIONS is defined,
+ * actions used by animdata will be duplicated.
  *
  * \note Usercount of new copy is always set to 1.
  *
  * \param bmain: Main database, may be NULL only if LIB_ID_CREATE_NO_MAIN is specified.
  * \param id: Source datablock.
  * \param r_newid: Pointer to new (copied) ID pointer.
- * \param flag: Set of copy options, see DNA_ID.h enum for details (leave to zero for default, full copy).
+ * \param flag: Set of copy options, see DNA_ID.h enum for details
+ * (leave to zero for default, full copy).
  * \return False when copying that ID type is not supported, true otherwise.
  */
 bool BKE_id_copy_ex(Main *bmain, const ID *id, ID **r_newid, const int flag)
@@ -848,7 +861,8 @@ bool id_single_user(bContext *C, ID *id, PointerRNA *ptr, PropertyRNA *prop)
   PointerRNA idptr;
 
   if (id) {
-    /* if property isn't editable, we're going to have an extra block hanging around until we save */
+    /* If property isn't editable,
+     * we're going to have an extra block hanging around until we save. */
     if (RNA_property_editable(ptr, prop)) {
       Main *bmain = CTX_data_main(C);
       /* copy animation actions too */
@@ -1372,7 +1386,9 @@ void *BKE_id_new(Main *bmain, const short type, const char *name)
   return id;
 }
 
-/** Generic helper to create a new temporary empty datablock of given type, *outside* of any Main database.
+/**
+ * Generic helper to create a new temporary empty datablock of given type,
+ * *outside* of any Main database.
  *
  * \param name: can be NULL, in which case we get default name for this ID type. */
 void *BKE_id_new_nomain(const short type, const char *name)
@@ -1743,7 +1759,8 @@ void id_clear_lib_data_ex(Main *bmain, ID *id, const bool id_in_mainlist)
     }
   }
 
-  /* Internal bNodeTree blocks inside datablocks also stores id->lib, make sure this stays in sync. */
+  /* Internal bNodeTree blocks inside datablocks also stores id->lib,
+   * make sure this stays in sync. */
   if ((ntree = ntreeFromID(id))) {
     id_clear_lib_data_ex(bmain, &ntree->id, false); /* Datablocks' nodetree is never in Main. */
   }
@@ -1788,14 +1805,15 @@ static void library_make_local_copying_check(ID *id,
 
     /* Our oh-so-beloved 'from' pointers... */
     if (entry->usage_flag & IDWALK_CB_LOOPBACK) {
-      /* We totally disregard Object->proxy_from 'usage' here, this one would only generate fake positives. */
+      /* We totally disregard Object->proxy_from 'usage' here,
+       * this one would only generate fake positives. */
       if (GS(par_id->name) == ID_OB) {
         BLI_assert(((Object *)par_id)->proxy_from == (Object *)id);
         continue;
       }
 
-      /* Shapekeys are considered 'private' to their owner ID here, and never tagged (since they cannot be linked),
-       * so we have to switch effective parent to their owner. */
+      /* Shapekeys are considered 'private' to their owner ID here, and never tagged
+       * (since they cannot be linked), * so we have to switch effective parent to their owner. */
       if (GS(par_id->name) == ID_KE) {
         par_id = ((Key *)par_id)->from;
       }
@@ -1809,8 +1827,9 @@ static void library_make_local_copying_check(ID *id,
       if (BLI_gset_haskey(loop_tags, par_id)) {
         /* We are in a 'dependency loop' of IDs, this does not say us anything, skip it.
          * Note that this is the situation that can lead to archipelagoes of linked data-blocks
-         * (since all of them have non-local users, they would all be duplicated, leading to a loop of unused
-         * linked data-blocks that cannot be freed since they all use each other...). */
+         * (since all of them have non-local users, they would all be duplicated,
+         * leading to a loop of unused linked data-blocks that cannot be freed since they all use
+         * each other...). */
         continue;
       }
       /* Else, recursively check that user ID. */
@@ -1818,10 +1837,12 @@ static void library_make_local_copying_check(ID *id,
     }
 
     if (par_id->tag & LIB_TAG_DOIT) {
-      /* This user will be fully local in future, so far so good, nothing to do here but check next user. */
+      /* This user will be fully local in future, so far so good,
+       * nothing to do here but check next user. */
     }
     else {
-      /* This user won't be fully local in future, so current ID won't be either. And we are done checking it. */
+      /* This user won't be fully local in future, so current ID won't be either.
+       * And we are done checking it. */
       id->tag &= ~LIB_TAG_DOIT;
       break;
     }
@@ -1835,15 +1856,16 @@ static void library_make_local_copying_check(ID *id,
  * \param bmain: Almost certainly global main.
  * \param lib: If not NULL, only make local datablocks from this library.
  * \param untagged_only: If true, only make local datablocks not tagged with LIB_TAG_PRE_EXISTING.
- * \param set_fake: If true, set fake user on all localized datablocks (except group and objects ones).
+ * \param set_fake: If true, set fake user on all localized data-blocks
+ * (except group and objects ones).
  */
-/* Note: Old (2.77) version was simply making (tagging) datablocks as local, without actually making any check whether
- * they were also indirectly used or not...
+/* Note: Old (2.77) version was simply making (tagging) data-blocks as local,
+ * without actually making any check whether * they were also indirectly used or not...
  *
- * Current version uses regular id_make_local callback, with advanced pre-processing step to detect all cases of
- * IDs currently indirectly used, but which will be used by local data only once this function is finished.
- * This allows to avoid any unneeded duplication of IDs, and hence all time lost afterwards to remove
- * orphaned linked data-blocks...
+ * Current version uses regular id_make_local callback, with advanced pre-processing step to detect
+ * all cases of IDs currently indirectly used, but which will be used by local data only once this
+ * function is finished.  This allows to avoid any unneeded duplication of IDs, and hence all time
+ * lost afterwards to remove orphaned linked data-blocks...
  */
 void BKE_library_make_local(Main *bmain,
                             const Library *lib,
@@ -1874,8 +1896,8 @@ void BKE_library_make_local(Main *bmain,
   for (int a = set_listbasepointers(bmain, lbarray); a--;) {
     ID *id = lbarray[a]->first;
 
-    /* Do not explicitly make local non-linkable IDs (shapekeys, in fact), they are assumed to be handled
-     * by real datablocks responsible of them. */
+    /* Do not explicitly make local non-linkable IDs (shapekeys, in fact),
+     * they are assumed to be handled by real datablocks responsible of them. */
     const bool do_skip = (id && !BKE_idcode_is_linkable(GS(id->name)));
 
     for (; id; id = id->next) {
@@ -1889,14 +1911,17 @@ void BKE_library_make_local(Main *bmain,
       if (id->lib == NULL) {
         id->tag &= ~(LIB_TAG_EXTERN | LIB_TAG_INDIRECT | LIB_TAG_NEW);
       }
-      /* The check on the fourth line (LIB_TAG_PRE_EXISTING) is done so its possible to tag data you don't want to
-       * be made local, used for appending data, so any libdata already linked wont become local (very nasty
+      /* The check on the fourth line (LIB_TAG_PRE_EXISTING) is done so it's possible to tag data
+       * you don't want to be made local, used for appending data,
+       * so any libdata already linked wont become local (very nasty
        * to discover all your links are lost after appending).
        * Also, never ever make proxified objects local, would not make any sense. */
       /* Some more notes:
        *   - Shapekeys are never tagged here (since they are not linkable).
-       *   - Nodetrees used in materials etc. have to be tagged manually, since they do not exist in Main (!).
-       * This is ok-ish on 'make local' side of things (since those are handled by their 'owner' IDs),
+       *   - Nodetrees used in materials etc. have to be tagged manually,
+       *     since they do not exist in Main (!).
+       * This is ok-ish on 'make local' side of things
+       * (since those are handled by their 'owner' IDs),
        * but complicates slightly the pre-processing of relations between IDs at step 2... */
       else if (!do_skip && id->tag & (LIB_TAG_EXTERN | LIB_TAG_INDIRECT | LIB_TAG_NEW) &&
                ELEM(lib, NULL, id->lib) &&
@@ -1905,8 +1930,9 @@ void BKE_library_make_local(Main *bmain,
         BLI_linklist_prepend_arena(&todo_ids, id, linklist_mem);
         id->tag |= LIB_TAG_DOIT;
 
-        /* Tag those nasty non-ID nodetrees, but do not add them to todo list, making them local is handled
-         * by 'owner' ID. This is needed for library_make_local_copying_check() to work OK at step 2. */
+        /* Tag those nasty non-ID nodetrees,
+         * but do not add them to todo list, making them local is handled by 'owner' ID.
+         * This is needed for library_make_local_copying_check() to work OK at step 2. */
         if (ntree != NULL) {
           ntree->tag |= LIB_TAG_DOIT;
         }
@@ -1923,8 +1949,9 @@ void BKE_library_make_local(Main *bmain,
   TIMEIT_VALUE_PRINT(make_local);
 #endif
 
-  /* Step 2: Check which datablocks we can directly make local (because they are only used by already, or future,
-   * local data), others will need to be duplicated. */
+  /* Step 2: Check which datablocks we can directly make local
+   * (because they are only used by already, or future, local data),
+   * others will need to be duplicated. */
   GSet *loop_tags = BLI_gset_ptr_new(__func__);
   for (LinkNode *it = todo_ids; it; it = it->next) {
     library_make_local_copying_check(it->link, loop_tags, bmain->relations, done_ids);
@@ -1942,15 +1969,17 @@ void BKE_library_make_local(Main *bmain,
 #endif
 
   /* Step 3: Make IDs local, either directly (quick and simple), or using generic process,
-   * which involves more complex checks and might instead create a local copy of original linked ID. */
+   * which involves more complex checks and might instead
+   * create a local copy of original linked ID. */
   for (LinkNode *it = todo_ids, *it_next; it; it = it_next) {
     it_next = it->next;
     ID *id = it->link;
 
     if (id->tag & LIB_TAG_DOIT) {
-      /* We know all users of this object are local or will be made fully local, even if currently there are
-       * some indirect usages. So instead of making a copy that we'll likely get rid of later, directly make
-       * that data block local. Saves a tremendous amount of time with complex scenes... */
+      /* We know all users of this object are local or will be made fully local, even if currently
+       * there are some indirect usages. So instead of making a copy that we'll likely get rid of
+       * later, directly make that data block local.
+       * Saves a tremendous amount of time with complex scenes... */
       id_clear_lib_data_ex(bmain, id, true);
       BKE_id_expand_local(bmain, id);
       id->tag &= ~LIB_TAG_DOIT;
@@ -1986,16 +2015,19 @@ void BKE_library_make_local(Main *bmain,
   TIMEIT_VALUE_PRINT(make_local);
 #endif
 
-  /* At this point, we are done with directly made local IDs. Now we have to handle duplicated ones, since their
+  /* At this point, we are done with directly made local IDs.
+   * Now we have to handle duplicated ones, since their
    * remaining linked original counterpart may not be needed anymore... */
   todo_ids = NULL;
 
-  /* Step 4: We have to remap local usages of old (linked) ID to new (local) ID in a separated loop,
+  /* Step 4: We have to remap local usages of old (linked) ID to new (local)
+   * ID in a separated loop,
    * as lbarray ordering is not enough to ensure us we did catch all dependencies
    * (e.g. if making local a parent object before its child...). See T48907. */
-  /* TODO This is now the biggest step by far (in term of processing time). We may be able to gain here by
-   * using again main->relations mapping, but... this implies BKE_libblock_remap & co to be able to update
-   * main->relations on the fly. Have to think about it a bit more, and see whether new code is OK first, anyway. */
+  /* TODO This is now the biggest step by far (in term of processing time).
+   * We may be able to gain here by using again main->relations mapping, but...
+   * this implies BKE_libblock_remap & co to be able to update main->relations on the fly.
+   * Have to think about it a bit more, and see whether new code is OK first, anyway. */
   for (LinkNode *it = copied_ids; it; it = it->next) {
     ID *id = it->link;
 
@@ -2076,10 +2108,11 @@ void BKE_library_make_local(Main *bmain,
 #endif
 
   /* This is probably more of a hack than something we should do here, but...
-   * Issue is, the whole copying + remapping done in complex cases above may leave pose channels of armatures
-   * in complete invalid state (more precisely, the bone pointers of the pchans - very crappy cross-datablocks
-   * relationship), se we tag it to be fully recomputed, but this does not seems to be enough in some cases,
-   * and evaluation code ends up trying to evaluate a not-yet-updated armature object's deformations.
+   * Issue is, the whole copying + remapping done in complex cases above may leave pose-channels of
+   * armatures in complete invalid state (more precisely, the bone pointers of the pose-channels -
+   * very crappy cross-data-blocks relationship), se we tag it to be fully recomputed,
+   * but this does not seems to be enough in some cases, and evaluation code ends up trying to
+   * evaluate a not-yet-updated armature object's deformations.
    * Try "make all local" in 04_01_H.lighting.blend from Agent327 without this, e.g. */
   for (Object *ob = bmain->objects.first; ob; ob = ob->id.next) {
     if (ob->data != NULL && ob->type == OB_ARMATURE && ob->pose != NULL &&
@@ -2160,7 +2193,8 @@ void BKE_libblock_rename(Main *bmain, ID *id, const char *name)
  *
  * \note Result is unique to a given ID type in a given Main database.
  *
- * \param name: An allocated string of minimal length MAX_ID_FULL_NAME, will be filled with generated string.
+ * \param name: An allocated string of minimal length #MAX_ID_FULL_NAME,
+ * will be filled with generated string.
  */
 void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const ID *id)
 {
@@ -2179,12 +2213,14 @@ void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const ID *id)
 }
 
 /**
- * Generate full name of the data-block (without ID code, but with library if any), with a 3-character prefix prepended
- * indicating whether it comes from a library, is overriding, has a fake or no user, etc.
+ * Generate full name of the data-block (without ID code, but with library if any),
+ * with a 3-character prefix prepended indicating whether it comes from a library,
+ * is overriding, has a fake or no user, etc.
  *
  * \note Result is unique to a given ID type in a given Main database.
  *
- * \param name: An allocated string of minimal length MAX_ID_FULL_NAME_UI, will be filled with generated string.
+ * \param name: An allocated string of minimal length #MAX_ID_FULL_NAME_UI,
+ * will be filled with generated string.
  */
 void BKE_id_full_name_ui_prefix_get(char name[MAX_ID_FULL_NAME_UI], const ID *id)
 {
@@ -2232,8 +2268,8 @@ void BKE_library_filepath_set(Main *bmain, Library *lib, const char *filepath)
      * outliner, and its not really supported but allow from here for now
      * since making local could cause this to be directly linked - campbell
      */
-    /* Never make paths relative to parent lib - reading code (blenloader) always set *all* lib->name relative to
-     * current main, not to their parent for indirectly linked ones. */
+    /* Never make paths relative to parent lib - reading code (blenloader) always set *all*
+     * lib->name relative to current main, not to their parent for indirectly linked ones. */
     const char *basepath = BKE_main_blendfile_path(bmain);
     BLI_path_abs(lib->filepath, basepath);
   }