Merge branch 'master' into soc-2021-uv-edge-select-supportsoc-2021-uv-edge-select-support

1 files changed, 22 insertions, 3 deletions

diff --git a/source/blender/editors/asset/ED_asset_catalog.hh b/source/blender/editors/asset/ED_asset_catalog.hh
index 8da8fc0d6c9..d4df15561d0 100644
--- a/source/blender/editors/asset/ED_asset_catalog.hh
+++ b/source/blender/editors/asset/ED_asset_catalog.hh
@@ -16,10 +16,17 @@
 
 /** \file
  * \ingroup edasset
+ *
+ * UI/Editor level API for catalog operations, creating richer functionality than the BKE catalog
+ * API provides (which this uses internally).
+ *
+ * Note that `ED_asset_catalog.h` is part of this API.
  */
 
 #pragma once
 
+#include <optional>
+
 #include "BKE_asset_catalog.hh"
 
 #include "BLI_string_ref.hh"
@@ -37,6 +44,18 @@ void ED_asset_catalog_remove(AssetLibrary *library, const blender::bke::CatalogI
 void ED_asset_catalog_rename(AssetLibrary *library,
                              blender::bke::CatalogID catalog_id,
                              blender::StringRefNull new_name);
-void ED_asset_catalog_move(AssetLibrary *library,
-                           blender::bke::CatalogID src_catalog_id,
-                           blender::bke::CatalogID dst_parent_catalog_id);
+/**
+ * Reinsert catalog identified by \a src_catalog_id as child to catalog identified by \a
+ * dst_parent_catalog_id. If \a dst_parent_catalog_id is not set, the catalog is moved to the root
+ * level of the tree.
+ * The name of the reinserted catalog is made unique within the parent. Note that moving a catalog
+ * to the same level it was before will also change its name, since the name uniqueness check isn't
+ * smart enough to ignore the item to be reinserted. So the caller is expected to handle this case
+ * to avoid unwanted renames.
+ *
+ * Nothing is done (debug builds run into an assert) if the given catalog IDs can't be identified.
+ */
+void ED_asset_catalog_move(
+    AssetLibrary *library,
+    blender::bke::CatalogID src_catalog_id,
+    std::optional<blender::bke::CatalogID> dst_parent_catalog_id = std::nullopt);