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, 2 insertions, 94 deletions

diff --git a/source/blender/blenkernel/intern/node.cc b/source/blender/blenkernel/intern/node.cc
index 6c1a0d2657f..7dce57a2773 100644
--- a/source/blender/blenkernel/intern/node.cc
+++ b/source/blender/blenkernel/intern/node.cc
@@ -542,7 +542,6 @@ static void write_node_socket_interface(BlendWriter *writer, bNodeSocket *sock)
   write_node_socket_default_value(writer, sock);
 }
 
-/* this is only direct data, tree itself should have been written */
 void ntreeBlendWrite(BlendWriter *writer, bNodeTree *ntree)
 {
   BKE_id_blend_write(writer, &ntree->id);
@@ -704,7 +703,6 @@ static void direct_link_node_socket(BlendDataReader *reader, bNodeSocket *sock)
   sock->declaration = nullptr;
 }
 
-/* ntree itself has been read! */
 void ntreeBlendReadData(BlendDataReader *reader, bNodeTree *ntree)
 {
   /* NOTE: writing and reading goes in sync, for speed. */
@@ -1296,14 +1294,6 @@ static void update_typeinfo(Main *bmain,
   FOREACH_NODETREE_END;
 }
 
-/**
- * Try to initialize all type-info in a node tree.
- *
- * \note In general undefined type-info is a perfectly valid case,
- * the type may just be registered later.
- * In that case the update_typeinfo function will set type-info on registration
- * and do necessary updates.
- */
 void ntreeSetTypes(const struct bContext *C, bNodeTree *ntree)
 {
   ntree->init |= NTREE_TYPE_INIT;
@@ -2059,13 +2049,11 @@ void nodeRemoveAllSockets(bNodeTree *ntree, bNode *node)
   node->update |= NODE_UPDATE;
 }
 
-/* finds a node based on its name */
 bNode *nodeFindNodebyName(bNodeTree *ntree, const char *name)
 {
   return (bNode *)BLI_findstring(&ntree->nodes, name, offsetof(bNode, name));
 }
 
-/* Finds a node based on given socket and returns true on success. */
 bool nodeFindNode(bNodeTree *ntree, bNodeSocket *sock, bNode **r_node, int *r_sockindex)
 {
   *r_node = nullptr;
@@ -2089,9 +2077,6 @@ bool nodeFindNode(bNodeTree *ntree, bNodeSocket *sock, bNode **r_node, int *r_so
   return false;
 }
 
-/**
- * \note Recursive
- */
 bNode *nodeFindRootParent(bNode *node)
 {
   if (node->parent) {
@@ -2100,10 +2085,6 @@ bNode *nodeFindRootParent(bNode *node)
   return node->type == NODE_FRAME ? node : nullptr;
 }
 
-/**
- * \returns true if \a child has \a parent as a parent/grandparent/...
- * \note Recursive
- */
 bool nodeIsChildOf(const bNode *parent, const bNode *child)
 {
   if (parent == child) {
@@ -2115,13 +2096,6 @@ bool nodeIsChildOf(const bNode *parent, const bNode *child)
   return false;
 }
 
-/**
- * Iterate over a chain of nodes, starting with \a node_start, executing
- * \a callback for each node (which can return false to end iterator).
- *
- * \param reversed: for backwards iteration
- * \note Recursive
- */
 void nodeChainIter(const bNodeTree *ntree,
                    const bNode *node_start,
                    bool (*callback)(bNode *, bNode *, void *, const bool),
@@ -2176,17 +2150,6 @@ static void iter_backwards_ex(const bNodeTree *ntree,
   }
 }
 
-/**
- * Iterate over a chain of nodes, starting with \a node_start, executing
- * \a callback for each node (which can return false to end iterator).
- *
- * Faster than nodeChainIter. Iter only once per node.
- * Can be called recursively (using another nodeChainIterBackwards) by
- * setting the recursion_lvl accordingly.
- *
- * \note Needs updated socket links (ntreeUpdateTree).
- * \note Recursive
- */
 void nodeChainIterBackwards(const bNodeTree *ntree,
                             const bNode *node_start,
                             bool (*callback)(bNode *, bNode *, void *),
@@ -2209,12 +2172,6 @@ void nodeChainIterBackwards(const bNodeTree *ntree,
   iter_backwards_ex(ntree, node_start, callback, userdata, recursion_mask);
 }
 
-/**
- * Iterate over all parents of \a node, executing \a callback for each parent
- * (which can return false to end iterator)
- *
- * \note Recursive
- */
 void nodeParentsIter(bNode *node, bool (*callback)(bNode *, void *), void *userdata)
 {
   if (node->parent) {
@@ -2227,7 +2184,6 @@ void nodeParentsIter(bNode *node, bool (*callback)(bNode *, void *), void *userd
 
 /* ************** Add stuff ********** */
 
-/* Find the first available, non-duplicate name for a given node */
 void nodeUniqueName(bNodeTree *ntree, bNode *node)
 {
   BLI_uniquename(
@@ -2290,9 +2246,6 @@ static void node_socket_copy(bNodeSocket *sock_dst, const bNodeSocket *sock_src,
   sock_dst->cache = nullptr;
 }
 
-/* keep socket listorder identical, for copying links */
-/* ntree is the target tree */
-/* unique_name needs to be true. It's only disabled for speed when doing GPUnodetrees. */
 bNode *BKE_node_copy_ex(bNodeTree *ntree,
                         const bNode *node_src,
                         const int flag,
@@ -2436,7 +2389,6 @@ static int node_count_links(const bNodeTree *ntree, const bNodeSocket *socket)
   return count;
 }
 
-/* also used via rna api, so we check for proper input output direction */
 bNodeLink *nodeAddLink(
     bNodeTree *ntree, bNode *fromnode, bNodeSocket *fromsock, bNode *tonode, bNodeSocket *tosock)
 {
@@ -2855,8 +2807,8 @@ bNodeTree *ntreeCopyTree(Main *bmain, const bNodeTree *ntree)
 /* XXX this should be removed eventually ...
  * Currently BKE functions are modeled closely on previous code,
  * using BKE_node_preview_init_tree to set up previews for a whole node tree in advance.
- * This should be left more to the individual node tree implementations.
- */
+ * This should be left more to the individual node tree implementations. */
+
 bool BKE_node_preview_used(const bNode *node)
 {
   /* XXX check for closed nodes? */
@@ -3089,9 +3041,6 @@ void BKE_node_preview_merge_tree(bNodeTree *to_ntree, bNodeTree *from_ntree, boo
   }
 }
 
-/* hack warning! this function is only used for shader previews, and
- * since it gets called multiple times per pixel for Ztransp we only
- * add the color once. Preview gets cleared before it starts render though */
 void BKE_node_preview_set_pixel(
     bNodePreview *preview, const float col[4], int x, int y, bool do_manage)
 {
@@ -3115,7 +3064,6 @@ void BKE_node_preview_set_pixel(
 
 /* ************** Free stuff ********** */
 
-/* goes over entire tree */
 void nodeUnlinkNode(bNodeTree *ntree, bNode *node)
 {
   LISTBASE_FOREACH_MUTABLE (bNodeLink *, link, &ntree->links) {
@@ -3305,8 +3253,6 @@ static void free_localized_node_groups(bNodeTree *ntree)
   }
 }
 
-/* Free (or release) any data used by this nodetree. Does not free the
- * nodetree itself and does no ID user counting. */
 void ntreeFreeTree(bNodeTree *ntree)
 {
   ntree_free_data(&ntree->id);
@@ -3410,12 +3356,6 @@ void ntreeSetOutput(bNodeTree *ntree)
    * might be different for editor or for "real" use... */
 }
 
-/**
- * Get address of potential node-tree pointer of given ID.
- *
- * \warning Using this function directly is potentially dangerous, if you don't know or are not
- * sure, please use `ntreeFromID()` instead.
- */
 bNodeTree **BKE_ntree_ptr_from_id(ID *id)
 {
   switch (GS(id->name)) {
@@ -3438,7 +3378,6 @@ bNodeTree **BKE_ntree_ptr_from_id(ID *id)
   }
 }
 
-/* Returns the private NodeTree object of the datablock, if it has one. */
 bNodeTree *ntreeFromID(ID *id)
 {
   bNodeTree **nodetree = BKE_ntree_ptr_from_id(id);
@@ -3477,7 +3416,6 @@ void ntreeNodeFlagSet(const bNodeTree *ntree, const int flag, const bool enable)
   }
 }
 
-/* returns localized tree for execution in threads */
 bNodeTree *ntreeLocalize(bNodeTree *ntree)
 {
   if (ntree) {
@@ -3516,9 +3454,6 @@ bNodeTree *ntreeLocalize(bNodeTree *ntree)
   return nullptr;
 }
 
-/* sync local composite with real tree */
-/* local tree is supposed to be running, be careful moving previews! */
-/* is called by jobs manager, outside threads, so it doesn't happen during draw */
 void ntreeLocalSync(bNodeTree *localtree, bNodeTree *ntree)
 {
   if (localtree && ntree) {
@@ -3528,8 +3463,6 @@ void ntreeLocalSync(bNodeTree *localtree, bNodeTree *ntree)
   }
 }
 
-/* merge local tree results back, and free local tree */
-/* we have to assume the editor already changed completely */
 void ntreeLocalMerge(Main *bmain, bNodeTree *localtree, bNodeTree *ntree)
 {
   if (ntree && localtree) {
@@ -3897,7 +3830,6 @@ static bNode *node_get_active_id_recursive(bNodeInstanceKey active_key,
   return nullptr;
 }
 
-/* two active flags, ID nodes have special flag for buttons display */
 bNode *nodeGetActiveID(bNodeTree *ntree, short idtype)
 {
   if (ntree) {
@@ -3940,7 +3872,6 @@ bool nodeSetActiveID(bNodeTree *ntree, short idtype, ID *id)
   return ok;
 }
 
-/* two active flags, ID nodes have special flag for buttons display */
 void nodeClearActiveID(bNodeTree *ntree, short idtype)
 {
   if (ntree == nullptr) {
@@ -3983,7 +3914,6 @@ void nodeClearActive(bNodeTree *ntree)
   }
 }
 
-/* two active flags, ID nodes have special flag for buttons display */
 void nodeSetActive(bNodeTree *ntree, bNode *node)
 {
   /* make sure only one node is active, and only one per ID type */
@@ -4052,10 +3982,6 @@ static void update_socket_declarations(ListBase *sockets,
   }
 }
 
-/**
- * Update `socket->declaration` for all sockets in the node. This assumes that the node declaration
- * and sockets are up to date already.
- */
 void nodeSocketDeclarationsUpdate(bNode *node)
 {
   BLI_assert(node->declaration != nullptr);
@@ -4063,10 +3989,6 @@ void nodeSocketDeclarationsUpdate(bNode *node)
   update_socket_declarations(&node->outputs, node->declaration->outputs());
 }
 
-/**
- * Just update `node->declaration` if necessary. This can also be called on nodes that may not be
- * up to date (e.g. because the need versioning or are dynamic).
- */
 bool nodeDeclarationEnsureOnOutdatedNode(bNodeTree *UNUSED(ntree), bNode *node)
 {
   if (node->declaration != nullptr) {
@@ -4088,10 +4010,6 @@ bool nodeDeclarationEnsureOnOutdatedNode(bNodeTree *UNUSED(ntree), bNode *node)
   return true;
 }
 
-/**
- * If the node implements a `declare` function, this function makes sure that `node->declaration`
- * is up to date. It is expected that the sockets of the node are up to date already.
- */
 bool nodeDeclarationEnsure(bNodeTree *ntree, bNode *node)
 {
   if (nodeDeclarationEnsureOnOutdatedNode(ntree, node)) {
@@ -4156,7 +4074,6 @@ void BKE_node_clipboard_clear(void)
 #endif
 }
 
-/* return false when one or more ID's are lost */
 bool BKE_node_clipboard_validate(void)
 {
   bool ok = true;
@@ -4258,7 +4175,6 @@ void BKE_node_clipboard_free(void)
 
 /* Node Instance Hash */
 
-/* magic number for initial hash key */
 const bNodeInstanceKey NODE_INSTANCE_KEY_BASE = {5381};
 const bNodeInstanceKey NODE_INSTANCE_KEY_NONE = {0};
 
@@ -5083,9 +4999,6 @@ static bool update_field_inferencing(bNodeTree &btree)
 
 }  // namespace blender::bke::node_field_inferencing
 
-/**
- * \param tree_update_flag: #eNodeTreeUpdate enum.
- */
 void ntreeUpdateAllUsers(Main *main, ID *id, const int tree_update_flag)
 {
   if (id == nullptr) {
@@ -5290,7 +5203,6 @@ void nodeLabel(bNodeTree *ntree, bNode *node, char *label, int maxlen)
   }
 }
 
-/* Get node socket label if it is set */
 const char *nodeSocketLabel(const bNodeSocket *sock)
 {
   return (sock->label[0] != '\0') ? sock->label : sock->name;
@@ -5472,10 +5384,6 @@ void node_type_size_preset(struct bNodeType *ntype, eNodeSizePreset size)
   }
 }
 
-/**
- * \warning Nodes defining a storage type _must_ allocate this for new nodes.
- * Otherwise nodes will reload as undefined (T46619).
- */
 void node_type_storage(bNodeType *ntype,
                        const char *storagename,
                        void (*freefunc)(struct bNode *node),