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, 0 insertions, 78 deletions

diff --git a/source/blender/blenkernel/intern/blendfile_link_append.c b/source/blender/blenkernel/intern/blendfile_link_append.c
index 6cb71c48a00..c265a6e2b7d 100644
--- a/source/blender/blenkernel/intern/blendfile_link_append.c
+++ b/source/blender/blenkernel/intern/blendfile_link_append.c
@@ -186,11 +186,6 @@ static void link_append_context_library_blohandle_release(
   }
 }
 
-/** Allocate and initialize a new context to link/append datablocks.
- *
- *  \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(LibraryLink_Params *params)
 {
   MemArena *ma = BLI_memarena_new(BLI_MEMARENA_STD_BUFSIZE, __func__);
@@ -202,7 +197,6 @@ BlendfileLinkAppendContext *BKE_blendfile_link_append_context_new(LibraryLink_Pa
   return lapp_context;
 }
 
-/** Free a link/append context. */
 void BKE_blendfile_link_append_context_free(BlendfileLinkAppendContext *lapp_context)
 {
   if (lapp_context->new_id_to_item != NULL) {
@@ -220,10 +214,6 @@ void BKE_blendfile_link_append_context_free(BlendfileLinkAppendContext *lapp_con
   BLI_memarena_free(lapp_context->memarena);
 }
 
-/** 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(BlendfileLinkAppendContext *lapp_context,
                                                 const int flag,
                                                 const bool do_set)
@@ -236,11 +226,6 @@ void BKE_blendfile_link_append_context_flag_set(BlendfileLinkAppendContext *lapp
   }
 }
 
-/** 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(
     BlendfileLinkAppendContext *lapp_context, const void *blendfile_mem, int blendfile_memsize)
 {
@@ -251,7 +236,6 @@ void BKE_blendfile_link_append_context_embedded_blendfile_set(
   lapp_context->blendfile_memsize = (size_t)blendfile_memsize;
 }
 
-/** Clear reference to Blender's embedded startup file into the context. */
 void BKE_blendfile_link_append_context_embedded_blendfile_clear(
     BlendfileLinkAppendContext *lapp_context)
 {
@@ -259,15 +243,6 @@ void BKE_blendfile_link_append_context_embedded_blendfile_clear(
   lapp_context->blendfile_memsize = 0;
 }
 
-/** 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(BlendfileLinkAppendContext *lapp_context,
                                                    const char *libname,
                                                    BlendHandle *blo_handle)
@@ -289,13 +264,6 @@ void BKE_blendfile_link_append_context_library_add(BlendfileLinkAppendContext *l
   lapp_context->num_libraries++;
 }
 
-/** Add a new item (datablock 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. */
 BlendfileLinkAppendContextItem *BKE_blendfile_link_append_context_item_add(
     BlendfileLinkAppendContext *lapp_context,
     const char *idname,
@@ -321,19 +289,6 @@ BlendfileLinkAppendContextItem *BKE_blendfile_link_append_context_item_add(
   return item;
 }
 
-/** 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(
     BlendfileLinkAppendContext *lapp_context,
     ReportList *reports,
@@ -385,8 +340,6 @@ int BKE_blendfile_link_append_context_item_idtypes_from_library_add(
   return id_num;
 }
 
-/** 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(
     BlendfileLinkAppendContext *UNUSED(lapp_context),
     BlendfileLinkAppendContextItem *item,
@@ -395,7 +348,6 @@ void BKE_blendfile_link_append_context_item_library_index_enable(
   BLI_BITMAP_ENABLE(item->libraries, 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)
 {
   return lapp_context->num_items == 0;
@@ -420,13 +372,6 @@ short BKE_blendfile_link_append_context_item_idcode_get(
   return item->idcode;
 }
 
-/** 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,
@@ -1014,11 +959,6 @@ static int foreach_libblock_link_append_callback(LibraryIDLinkCallbackData *cb_d
 /** \name Library link/append code.
  * \{ */
 
-/** 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(BlendfileLinkAppendContext *lapp_context, ReportList *reports)
 {
   if (lapp_context->num_items == 0) {
@@ -1287,7 +1227,6 @@ void BKE_blendfile_append(BlendfileLinkAppendContext *lapp_context, ReportList *
   BKE_main_id_newptr_and_tag_clear(bmain);
 }
 
-/** Perform linking operation on all items added to given `lapp_context`. */
 void BKE_blendfile_link(BlendfileLinkAppendContext *lapp_context, ReportList *reports)
 {
   if (lapp_context->num_items == 0) {
@@ -1481,23 +1420,6 @@ static void blendfile_library_relocate_remap(Main *bmain,
   }
 }
 
-/** 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(BlendfileLinkAppendContext *lapp_context,
                                     ReportList *reports,
                                     Library *library,