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, 187 insertions, 12 deletions

diff --git a/source/blender/blenkernel/BKE_node.h b/source/blender/blenkernel/BKE_node.h
index f925834beac..57eab4f76cf 100644
--- a/source/blender/blenkernel/BKE_node.h
+++ b/source/blender/blenkernel/BKE_node.h
@@ -436,20 +436,44 @@ struct GHashIterator *ntreeTypeGetIterator(void);
   } \
   (void)0
 
+/**
+ * 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, struct bNodeTree *ntree);
 
 struct bNodeTree *ntreeAddTree(struct Main *bmain, const char *name, const char *idname);
 
 /* copy/free funcs, need to manage ID users */
+
+/**
+ * Free (or release) any data used by this node-tree.
+ * Does not free the node-tree itself and does no ID user counting.
+ */
 void ntreeFreeTree(struct bNodeTree *ntree);
-/* Free tree which is embedded into another datablock. */
+/**
+ * Free tree which is embedded into another data-block.
+ */
 void ntreeFreeEmbeddedTree(struct bNodeTree *ntree);
 struct bNodeTree *ntreeCopyTree_ex(const struct bNodeTree *ntree,
                                    struct Main *bmain,
                                    const bool do_id_user);
 struct bNodeTree *ntreeCopyTree(struct Main *bmain, const struct bNodeTree *ntree);
 
+/**
+ * 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.
+ */
 struct bNodeTree **BKE_ntree_ptr_from_id(struct ID *id);
+/**
+ * Returns the private NodeTree object of the data-block, if it has one.
+ */
 struct bNodeTree *ntreeFromID(struct ID *id);
 
 void ntreeFreeLocalNode(struct bNodeTree *ntree, struct bNode *node);
@@ -459,13 +483,17 @@ bool ntreeHasType(const struct bNodeTree *ntree, int type);
 bool ntreeHasTree(const struct bNodeTree *ntree, const struct bNodeTree *lookup);
 void ntreeUpdateTree(struct Main *main, struct bNodeTree *ntree);
 void ntreeUpdateAllNew(struct Main *main);
+/**
+ * \param tree_update_flag: #eNodeTreeUpdate enum.
+ */
 void ntreeUpdateAllUsers(struct Main *main, struct ID *id, int tree_update_flag);
 
 void ntreeGetDependencyList(struct bNodeTree *ntree,
                             struct bNode ***r_deplist,
                             int *r_deplist_len);
 
-/* XXX old trees handle output flags automatically based on special output
+/**
+ * XXX: old trees handle output flags automatically based on special output
  * node types and last active selection.
  * New tree types have a per-output socket flag to indicate the final output to use explicitly.
  */
@@ -476,11 +504,31 @@ void ntreeFreeCache(struct bNodeTree *ntree);
 bool ntreeNodeExists(const struct bNodeTree *ntree, const struct bNode *testnode);
 bool ntreeOutputExists(const struct bNode *node, const struct bNodeSocket *testsock);
 void ntreeNodeFlagSet(const bNodeTree *ntree, const int flag, const bool enable);
+/**
+ * Returns localized tree for execution in threads.
+ */
 struct bNodeTree *ntreeLocalize(struct bNodeTree *ntree);
+/**
+ * Sync local composite with real tree.
+ * The 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(struct bNodeTree *localtree, struct bNodeTree *ntree);
+/**
+ * Merge local tree results back, and free local tree.
+ *
+ * We have to assume the editor already changed completely.
+ */
 void ntreeLocalMerge(struct Main *bmain, struct bNodeTree *localtree, struct bNodeTree *ntree);
 
+/**
+ * This is only direct data, tree itself should have been written.
+ */
 void ntreeBlendWrite(struct BlendWriter *writer, struct bNodeTree *ntree);
+/**
+ * \note `ntree` itself has been read!
+ */
 void ntreeBlendReadData(struct BlendDataReader *reader, struct bNodeTree *ntree);
 void ntreeBlendReadLib(struct BlendLibReader *reader, struct bNodeTree *ntree);
 void ntreeBlendReadExpand(struct BlendExpander *expander, struct bNodeTree *ntree);
@@ -614,27 +662,42 @@ void nodeModifySocketTypeStatic(
 
 struct bNode *nodeAddNode(const struct bContext *C, struct bNodeTree *ntree, const char *idname);
 struct bNode *nodeAddStaticNode(const struct bContext *C, struct bNodeTree *ntree, int type);
+/**
+ * \note Goes over entire tree.
+ */
 void nodeUnlinkNode(struct bNodeTree *ntree, struct bNode *node);
+/**
+ * Find the first available, non-duplicate name for a given node.
+ */
 void nodeUniqueName(struct bNodeTree *ntree, struct bNode *node);
 
-/* Delete node, associated animation data and ID user count. */
+/**
+ * Delete node, associated animation data and ID user count.
+ */
 void nodeRemoveNode(struct Main *bmain,
                     struct bNodeTree *ntree,
                     struct bNode *node,
                     bool do_id_user);
 
+/**
+ * \param ntree: is the target tree.
+ *
+ * \note keep socket list order identical, for copying links.
+ * \note `unique_name` needs to be true. It's only disabled for speed when doing GPUnodetrees.
+ */
 struct bNode *BKE_node_copy_ex(struct bNodeTree *ntree,
                                const struct bNode *node_src,
                                const int flag,
                                const bool unique_name);
 
-/* Same as BKE_node_copy_ex() but stores pointers to a new node and its sockets in the source
- * node.
+/**
+ * Same as #BKE_node_copy_ex but stores pointers to a new node and its sockets in the source node.
  *
  * NOTE: DANGER ZONE!
  *
  * TODO(sergey): Maybe it's better to make BKE_node_copy_ex() return a mapping from old node and
- * sockets to new one. */
+ * sockets to new one.
+ */
 struct bNode *BKE_node_copy_store_new_pointers(struct bNodeTree *ntree,
                                                struct bNode *node_src,
                                                const int flag);
@@ -642,6 +705,9 @@ struct bNodeTree *ntreeCopyTree_ex_new_pointers(const struct bNodeTree *ntree,
                                                 struct Main *bmain,
                                                 const bool do_id_user);
 
+/**
+ * Also used via RNA API, so we check for proper input output direction.
+ */
 struct bNodeLink *nodeAddLink(struct bNodeTree *ntree,
                               struct bNode *fromnode,
                               struct bNodeSocket *fromsock,
@@ -665,25 +731,62 @@ void nodePositionRelative(struct bNode *from_node,
                           struct bNodeSocket *to_sock);
 void nodePositionPropagate(struct bNode *node);
 
+/**
+ * Finds a node based on its name.
+ */
 struct bNode *nodeFindNodebyName(struct bNodeTree *ntree, const char *name);
+/**
+ * Finds a node based on given socket and returns true on success.
+ */
 bool nodeFindNode(struct bNodeTree *ntree,
                   struct bNodeSocket *sock,
                   struct bNode **r_node,
                   int *r_sockindex);
+/**
+ * \note Recursive.
+ */
 struct bNode *nodeFindRootParent(bNode *node);
 
+/**
+ * \returns true if \a child has \a parent as a parent/grandparent/... etc.
+ * \note Recursive
+ */
 bool nodeIsChildOf(const bNode *parent, const bNode *child);
 
+/**
+ * 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),
                    void *userdata,
                    const bool reversed);
+/**
+ * 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 *),
                             void *userdata,
                             int recursion_lvl);
+/**
+ * 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);
 
 struct bNodeLink *nodeFindLink(struct bNodeTree *ntree,
@@ -692,11 +795,20 @@ struct bNodeLink *nodeFindLink(struct bNodeTree *ntree,
 int nodeCountSocketLinks(const struct bNodeTree *ntree, const struct bNodeSocket *sock);
 
 void nodeSetSelected(struct bNode *node, bool select);
+/**
+ * Two active flags, ID nodes have special flag for buttons display.
+ */
 void nodeSetActive(struct bNodeTree *ntree, struct bNode *node);
 struct bNode *nodeGetActive(struct bNodeTree *ntree);
+/**
+ * Two active flags, ID nodes have special flag for buttons display.
+ */
 struct bNode *nodeGetActiveID(struct bNodeTree *ntree, short idtype);
 bool nodeSetActiveID(struct bNodeTree *ntree, short idtype, struct ID *id);
 void nodeClearActive(struct bNodeTree *ntree);
+/**
+ * Two active flags, ID nodes have special flag for buttons display.
+ */
 void nodeClearActiveID(struct bNodeTree *ntree, short idtype);
 struct bNode *nodeGetActiveTexture(struct bNodeTree *ntree);
 
@@ -712,14 +824,31 @@ void nodeSetSocketAvailability(struct bNodeTree *ntree,
 
 int nodeSocketLinkLimit(const struct bNodeSocket *sock);
 
+/**
+ * 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(struct bNodeTree *ntree, struct bNode *node);
+/**
+ * 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(struct bNodeTree *ntree, struct bNode *node);
+/**
+ * Update `socket->declaration` for all sockets in the node. This assumes that the node declaration
+ * and sockets are up to date already.
+ */
 void nodeSocketDeclarationsUpdate(struct bNode *node);
 
-/* Node Clipboard */
+/**
+ * Node Clipboard.
+ */
 void BKE_node_clipboard_init(const struct bNodeTree *ntree);
 void BKE_node_clipboard_clear(void);
 void BKE_node_clipboard_free(void);
+/**
+ * Return false when one or more ID's are lost.
+ */
 bool BKE_node_clipboard_validate(void);
 void BKE_node_clipboard_add_node(struct bNode *node);
 void BKE_node_clipboard_add_link(struct bNodeLink *link);
@@ -727,7 +856,9 @@ const struct ListBase *BKE_node_clipboard_get_nodes(void);
 const struct ListBase *BKE_node_clipboard_get_links(void);
 int BKE_node_clipboard_get_type(void);
 
-/* Node Instance Hash */
+/**
+ * Node Instance Hash.
+ */
 typedef struct bNodeInstanceHash {
   /** XXX should be made a direct member, #GHash allocation needs to support it */
   GHash *ghash;
@@ -735,6 +866,9 @@ typedef struct bNodeInstanceHash {
 
 typedef void (*bNodeInstanceValueFP)(void *value);
 
+/**
+ * Magic number for initial hash key.
+ */
 extern const bNodeInstanceKey NODE_INSTANCE_KEY_BASE;
 extern const bNodeInstanceKey NODE_INSTANCE_KEY_NONE;
 
@@ -819,6 +953,11 @@ void BKE_node_preview_merge_tree(struct bNodeTree *to_ntree,
                                  struct bNodeTree *from_ntree,
                                  bool remove_old);
 
+/**
+ * Hack warning! this function is only used for shader previews,
+ * and since it gets called multiple times per pixel for Z-transparency we only add the color once.
+ * Preview gets cleared before it starts render though.
+ */
 void BKE_node_preview_set_pixel(
     struct bNodePreview *preview, const float col[4], int x, int y, bool do_manage);
 
@@ -829,13 +968,18 @@ void BKE_node_preview_set_pixel(
  * \{ */
 
 void nodeLabel(struct bNodeTree *ntree, struct bNode *node, char *label, int maxlen);
+/**
+ * Get node socket label if it is set.
+ */
 const char *nodeSocketLabel(const struct bNodeSocket *sock);
 
 bool nodeGroupPoll(struct bNodeTree *nodetree,
                    struct bNodeTree *grouptree,
                    const char **r_disabled_hint);
 
-/* Init a new node type struct with default values and callbacks */
+/**
+ * Initialize a new node type struct with default values and callbacks.
+ */
 void node_type_base(struct bNodeType *ntype, int type, const char *name, short nclass, short flag);
 void node_type_base_custom(
     struct bNodeType *ntype, const char *idname, const char *name, short nclass, short flag);
@@ -846,6 +990,10 @@ void node_type_size(struct bNodeType *ntype, int width, int minwidth, int maxwid
 void node_type_size_preset(struct bNodeType *ntype, eNodeSizePreset size);
 void node_type_init(struct bNodeType *ntype,
                     void (*initfunc)(struct bNodeTree *ntree, struct bNode *node));
+/**
+ * \warning Nodes defining a storage type _must_ allocate this for new nodes.
+ * Otherwise nodes will reload as undefined (T46619).
+ */
 void node_type_storage(struct bNodeType *ntype,
                        const char *storagename,
                        void (*freefunc)(struct bNode *node),
@@ -1095,8 +1243,18 @@ void BKE_nodetree_remove_layer_n(struct bNodeTree *ntree,
 
 struct bNodeTreeExec *ntreeShaderBeginExecTree(struct bNodeTree *ntree);
 void ntreeShaderEndExecTree(struct bNodeTreeExec *exec);
+/**
+   Find an output node of the shader tree.
+ *
+ * \note it will only return output which is NOT in the group, which isn't how
+ * render engines works but it's how the GPU shader compilation works. This we
+ * can change in the future and make it a generic function, but for now it stays
+ * private here.
+ */
 struct bNode *ntreeShaderOutputNode(struct bNodeTree *ntree, int target);
-
+/**
+ * This one needs to work on a local tree.
+ */
 void ntreeGPUMaterialNodes(struct bNodeTree *localtree,
                            struct GPUMaterial *mat,
                            bool *has_surface_output,
@@ -1288,7 +1446,22 @@ void ntreeCompositExecTree(struct Scene *scene,
                            const struct ColorManagedViewSettings *view_settings,
                            const struct ColorManagedDisplaySettings *display_settings,
                            const char *view_name);
+
+/**
+ * Called from render pipeline, to tag render input and output.
+ * need to do all scenes, to prevent errors when you re-render 1 scene.
+ */
 void ntreeCompositTagRender(struct Scene *scene);
+/**
+ * Update the outputs of the render layer nodes.
+ * Since the outputs depend on the render engine, this part is a bit complex:
+ * - #ntreeCompositUpdateRLayers is called and loops over all render layer nodes.
+ * - Each render layer node calls the update function of the
+ *   render engine that's used for its scene.
+ * - The render engine calls RE_engine_register_pass for each pass.
+ * - #RE_engine_register_pass calls #ntreeCompositRegisterPass,
+ *   which calls #node_cmp_rlayers_register_pass for every render layer node.
+ */
 void ntreeCompositUpdateRLayers(struct bNodeTree *ntree);
 void ntreeCompositRegisterPass(struct bNodeTree *ntree,
                                struct Scene *scene,
@@ -1329,8 +1502,10 @@ void ntreeCompositCryptomatteLayerPrefix(const Scene *scene,
                                          const bNode *node,
                                          char *r_prefix,
                                          size_t prefix_len);
-/* Update the runtime layer names with the crypto-matte layer names of the references
- * render layer or image. */
+/**
+ * Update the runtime layer names with the crypto-matte layer names of the references render layer
+ * or image.
+ */
 void ntreeCompositCryptomatteUpdateLayerNames(const Scene *scene, bNode *node);
 struct CryptomatteSession *ntreeCompositCryptomatteSession(const Scene *scene, bNode *node);