[Bf-blender-cvs] [9183f9f8602] master: Cleanup/Documentation: Add/move comments for asset files

[Julian Eisel]

Commit: 9183f9f8602aac82aae5319d5a9e75bc830b3fa7
Author: Julian Eisel
Date:   Thu Dec 9 11:56:52 2021 +0100
Branches: master
https://developer.blender.org/rB9183f9f8602aac82aae5319d5a9e75bc830b3fa7

Cleanup/Documentation: Add/move comments for asset files

Adds some basic high-level explanations for editor/UI level asset APIs.
Also moves one such comment from the source file to the header file,
so it's in the same file as other API comments.

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

M	source/blender/editors/asset/ED_asset_catalog.h
M	source/blender/editors/asset/ED_asset_catalog.hh
M	source/blender/editors/asset/ED_asset_filter.h
M	source/blender/editors/asset/ED_asset_handle.h
M	source/blender/editors/asset/ED_asset_temp_id_consumer.h
M	source/blender/editors/asset/intern/asset_handle.cc

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

diff --git a/source/blender/editors/asset/ED_asset_catalog.h b/source/blender/editors/asset/ED_asset_catalog.h
index 451ec0d5984..be99de01173 100644
--- a/source/blender/editors/asset/ED_asset_catalog.h
+++ b/source/blender/editors/asset/ED_asset_catalog.h
@@ -16,6 +16,8 @@
 
 /** \file
  * \ingroup edasset
+ *
+ * Supplement for `ED_asset_catalog.hh`. Part of the same API but usable in C.
  */
 
 #pragma once
diff --git a/source/blender/editors/asset/ED_asset_catalog.hh b/source/blender/editors/asset/ED_asset_catalog.hh
index cbfce16e9eb..d4df15561d0 100644
--- a/source/blender/editors/asset/ED_asset_catalog.hh
+++ b/source/blender/editors/asset/ED_asset_catalog.hh
@@ -16,6 +16,11 @@
 
 /** \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
diff --git a/source/blender/editors/asset/ED_asset_filter.h b/source/blender/editors/asset/ED_asset_filter.h
index de18b5fff1e..3b92baea117 100644
--- a/source/blender/editors/asset/ED_asset_filter.h
+++ b/source/blender/editors/asset/ED_asset_filter.h
@@ -16,6 +16,8 @@
 
 /** \file
  * \ingroup edasset
+ *
+ * Functions for filtering assets.
  */
 
 #pragma once
diff --git a/source/blender/editors/asset/ED_asset_handle.h b/source/blender/editors/asset/ED_asset_handle.h
index efb99410d3d..dce851164a5 100644
--- a/source/blender/editors/asset/ED_asset_handle.h
+++ b/source/blender/editors/asset/ED_asset_handle.h
@@ -16,6 +16,12 @@
 
 /** \file
  * \ingroup edasset
+ *
+ * Asset-handle is a temporary design, not part of the core asset system design.
+ *
+ * Currently asset-list items are just file directory items (#FileDirEntry). So an asset-handle
+ * just wraps a pointer to this. We try to abstract away the fact that it's just a file entry,
+ * although that doesn't always work (see #rna_def_asset_handle()).
  */
 
 #pragma once
diff --git a/source/blender/editors/asset/ED_asset_temp_id_consumer.h b/source/blender/editors/asset/ED_asset_temp_id_consumer.h
index 9a47e435612..0848f4225bd 100644
--- a/source/blender/editors/asset/ED_asset_temp_id_consumer.h
+++ b/source/blender/editors/asset/ED_asset_temp_id_consumer.h
@@ -16,6 +16,11 @@
 
 /** \file
  * \ingroup edasset
+ *
+ * API to abstract away details for temporary loading of an ID from an asset. If the ID is stored
+ * in the current file (or more precisely, in the #Main given when requesting an ID) no loading is
+ * performed and the ID is returned. Otherwise it's imported for temporary access using the
+ * `BLO_library_temp` API.
  */
 
 #pragma once
diff --git a/source/blender/editors/asset/intern/asset_handle.cc b/source/blender/editors/asset/intern/asset_handle.cc
index 363bd9226da..a2029d3cc50 100644
--- a/source/blender/editors/asset/intern/asset_handle.cc
+++ b/source/blender/editors/asset/intern/asset_handle.cc
@@ -16,12 +16,6 @@
 
 /** \file
  * \ingroup edasset
- *
- * Asset-handle is a temporary design, not part of the core asset system design.
- *
- * Currently asset-list items are just file directory items (#FileDirEntry). So an asset-handle is
- * just wraps a pointer to this. We try to abstract away the fact that it's just a file entry,
- * although that doesn't always work (see #rna_def_asset_handle()).
  */
 
 #include <string>