Cleanup: move public doc-strings into headers for 'blenkernel'

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 104 insertions, 2 deletions

diff --git a/source/blender/blenkernel/BKE_blendfile_link_append.h b/source/blender/blenkernel/BKE_blendfile_link_append.h
index f8db1b2c435..52b8cc8c6f2 100644
--- a/source/blender/blenkernel/BKE_blendfile_link_append.h
+++ b/source/blender/blenkernel/BKE_blendfile_link_append.h
@@ -36,23 +36,65 @@ struct View3D;
 typedef struct BlendfileLinkAppendContext BlendfileLinkAppendContext;
 typedef struct BlendfileLinkAppendContextItem BlendfileLinkAppendContextItem;
 
+/**
+ * Allocate and initialize a new context to link/append data-blocks.
+ *
+ *  \param flag: A combination of #eFileSel_Params_Flag from DNA_space_types.h & #eBLOLibLinkFlags
+ * from BLO_readfile.h
+ */
 BlendfileLinkAppendContext *BKE_blendfile_link_append_context_new(
     struct LibraryLink_Params *params);
+/**
+ * Free a link/append context.
+ */
 void BKE_blendfile_link_append_context_free(struct BlendfileLinkAppendContext *lapp_context);
+/**
+ * Set or clear flags in given \a lapp_context.
+ *
+ * \param do_set: Set the given \a flag if true, clear it otherwise.
+ */
 void BKE_blendfile_link_append_context_flag_set(struct BlendfileLinkAppendContext *lapp_context,
                                                 const int flag,
                                                 const bool do_set);
 
+/**
+ * Store reference to a Blender's embedded memfile into the context.
+ *
+ * \note This is required since embedded startup blender file is handled in `ED` module, which
+ * cannot be linked in BKE code.
+ */
 void BKE_blendfile_link_append_context_embedded_blendfile_set(
     struct BlendfileLinkAppendContext *lapp_context,
     const void *blendfile_mem,
     int blendfile_memsize);
+/** Clear reference to Blender's embedded startup file into the context. */
 void BKE_blendfile_link_append_context_embedded_blendfile_clear(
     struct BlendfileLinkAppendContext *lapp_context);
 
+/**
+ * Add a new source library to search for items to be linked to the given link/append context.
+ *
+ * \param libname: the absolute path to the library blend file.
+ * \param blo_handle: the blend file handle of the library, NULL is not available. Note that this
+ *                    is only borrowed for linking purpose, no releasing or other management will
+ *                    be performed by #BKE_blendfile_link_append code on it.
+ *
+ * \note *Never* call #BKE_blendfile_link_append_context_library_add()
+ * after having added some items.
+ */
 void BKE_blendfile_link_append_context_library_add(struct BlendfileLinkAppendContext *lapp_context,
                                                    const char *libname,
                                                    struct BlendHandle *blo_handle);
+/**
+ * Add a new item (data-block name and `idcode`) to be searched and linked/appended from libraries
+ * associated to the given context.
+ *
+ * \param userdata: an opaque user-data pointer stored in generated link/append item.
+ *
+ * TODO: Add a more friendly version of this that combines it with the call to
+ * #BKE_blendfile_link_append_context_item_library_index_enable to enable the added item for all
+ * added library sources.
+ */
 struct BlendfileLinkAppendContextItem *BKE_blendfile_link_append_context_item_add(
     struct BlendfileLinkAppendContext *lapp_context,
     const char *idname,
@@ -60,16 +102,37 @@ struct BlendfileLinkAppendContextItem *BKE_blendfile_link_append_context_item_ad
     void *userdata);
 
 #define BLENDFILE_LINK_APPEND_INVALID -1
+/**
+ * Search for all ID matching given `id_types_filter` in given `library_index`, and add them to
+ * the list of items to process.
+ *
+ * \note #BKE_blendfile_link_append_context_library_add should never be called on the same
+ *`lapp_context` after this function.
+ *
+ * \param id_types_filter: A set of `FILTER_ID` bitflags, the types of IDs to add to the items
+ *                         list.
+ * \param library_index: The index of the library to look into, in given `lapp_context`.
+ *
+ * \return The number of items found and added to the list, or `BLENDFILE_LINK_APPEND_INVALID` if
+ *         it could not open the .blend file.
+ */
 int BKE_blendfile_link_append_context_item_idtypes_from_library_add(
     struct BlendfileLinkAppendContext *lapp_context,
     struct ReportList *reports,
     const uint64_t id_types_filter,
     const int library_index);
 
+/**
+ * Enable search of the given \a item into the library stored at given index in the link/append
+ * context.
+ */
 void BKE_blendfile_link_append_context_item_library_index_enable(
     struct BlendfileLinkAppendContext *lapp_context,
     struct BlendfileLinkAppendContextItem *item,
     const int library_index);
+/**
+ * Check if given link/append context is empty (has no items to process) or not.
+ */
 bool BKE_blendfile_link_append_context_is_empty(struct BlendfileLinkAppendContext *lapp_context);
 
 void *BKE_blendfile_link_append_context_item_userdata_get(
@@ -89,27 +152,66 @@ typedef enum eBlendfileLinkAppendForeachItemFlag {
    * See comments in #foreach_libblock_link_append_callback. */
   BKE_BLENDFILE_LINK_APPEND_FOREACH_ITEM_FLAG_DO_INDIRECT = 1 << 0,
 } eBlendfileLinkAppendForeachItemFlag;
-/** Callback called by #BKE_blendfile_link_append_context_item_foreach over each (or a subset of
+/**
+ * Callback called by #BKE_blendfile_link_append_context_item_foreach over each (or a subset of
  * each) of the items in given #BlendfileLinkAppendContext.
  *
  * \param userdata: An opaque void pointer passed to the `callback_function`.
  *
- * \return `true` if iteration should continue, `false` otherwise. */
+ * \return `true` if iteration should continue, `false` otherwise.
+ */
 typedef bool (*BKE_BlendfileLinkAppendContexteItemFunction)(
     struct BlendfileLinkAppendContext *lapp_context,
     struct BlendfileLinkAppendContextItem *item,
     void *userdata);
+/**
+ * Iterate over all (or a subset) of the items listed in given #BlendfileLinkAppendContext,
+ * and call the `callback_function` on them.
+ *
+ * \param flag: Control which type of items to process (see
+ * #eBlendfileLinkAppendForeachItemFlag enum flags).
+ * \param userdata: An opaque void pointer passed to the `callback_function`.
+ */
 void BKE_blendfile_link_append_context_item_foreach(
     struct BlendfileLinkAppendContext *lapp_context,
     BKE_BlendfileLinkAppendContexteItemFunction callback_function,
     const eBlendfileLinkAppendForeachItemFlag flag,
     void *userdata);
 
+/**
+ * Perform append operation, using modern ID usage looper to detect which ID should be kept
+ * linked, made local, duplicated as local, re-used from local etc.
+ *
+ * The IDs processed by this functions are the one that have been linked by a previous call to
+ * #BKE_blendfile_link on the same `lapp_context`.
+ */
 void BKE_blendfile_append(struct BlendfileLinkAppendContext *lapp_context,
                           struct ReportList *reports);
+/**
+ * Perform linking operation on all items added to given `lapp_context`.
+ */
 void BKE_blendfile_link(struct BlendfileLinkAppendContext *lapp_context,
                         struct ReportList *reports);
 
+/**
+ * Try to relocate all linked IDs added to `lapp_context`, belonging to the given `library`.
+ *
+ * This function searches for matching IDs (type and name) in all libraries added to the given
+ * `lapp_context`.
+ *
+ * Typical usages include:
+ * - Relocating a library:
+ *   - Add the new target library path to `lapp_context`.
+ *   - Add all IDs from the library to relocate to `lapp_context`
+ *   - Mark the new target library to be considered for each ID.
+ *   - Call this function.
+ *
+ * - Searching for (e.g.missing) linked IDs in a set or sub-set of libraries:
+ *   - Add all potential library sources paths to `lapp_context`.
+ *   - Add all IDs to search for to `lapp_context`.
+ *   - Mark which libraries should be considered for each ID.
+ *   - Call this function.
+ */
 void BKE_blendfile_library_relocate(struct BlendfileLinkAppendContext *lapp_context,
                                     struct ReportList *reports,
                                     struct Library *library,