[Bf-blender-cvs] [bf55ab38d88] functions: comment on llvm builder and types

[Jacques Lucke]

Commit: bf55ab38d8846544b9a2d95c2ab93b167953fc51
Author: Jacques Lucke
Date:   Wed Jul 3 15:16:22 2019 +0200
Branches: functions
https://developer.blender.org/rBbf55ab38d8846544b9a2d95c2ab93b167953fc51

comment on llvm builder and types

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

M	source/blender/functions/backends/llvm/builder.hpp
M	source/blender/functions/backends/llvm/llvm_types.hpp

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

diff --git a/source/blender/functions/backends/llvm/builder.hpp b/source/blender/functions/backends/llvm/builder.hpp
index 6984de8a6c0..6bf235bfd2b 100644
--- a/source/blender/functions/backends/llvm/builder.hpp
+++ b/source/blender/functions/backends/llvm/builder.hpp
@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * This is a wrapper for llvm::IRBuilder<>. It allows extending the normal builder with methods
+ * that are helpful for the use cases in Blender.
+ */
+
 #include "FN_core.hpp"
 #include <llvm/IR/IRBuilder.h>
 
diff --git a/source/blender/functions/backends/llvm/llvm_types.hpp b/source/blender/functions/backends/llvm/llvm_types.hpp
index afbda11bdc9..c81d3046403 100644
--- a/source/blender/functions/backends/llvm/llvm_types.hpp
+++ b/source/blender/functions/backends/llvm/llvm_types.hpp
@@ -9,22 +9,64 @@
 
 namespace FN {
 
+/**
+ * This is the main type extension for llvm types.
+ */
 class LLVMTypeInfo : public TypeExtension {
  public:
   BLI_COMPOSITION_DECLARATION(LLVMTypeInfo);
 
   virtual ~LLVMTypeInfo();
 
+  /**
+   * Return the llvm::Type object corresponding to the parent FN::Type. Note, that llvm::Type
+   * objects belong to some LLVMContext and therefore cannot be stored globally. Different
+   * LLVMContexts exist when llvm is used from multiple threads at the same time.
+   */
   virtual llvm::Type *get_type(llvm::LLVMContext &context) const = 0;
+
+  /**
+   * Build the code to create a copy of the given value. Since values are immutable in llvm, this
+   * function can just return the original value. Only when it is e.g. a pointer to some outside
+   * object, that has to be copied, a non trivial implementation has to be provided.
+   */
   virtual llvm::Value *build_copy_ir(CodeBuilder &builder, llvm::Value *value) const = 0;
+
+  /**
+   * Build code to free the given value.
+   */
   virtual void build_free_ir(CodeBuilder &builder, llvm::Value *value) const = 0;
+
+  /**
+   * Build code to relocate the value to a specific memory address. The original value in the
+   * virtual register should be freed.
+   *
+   * Usually, it should be possible to interpret the stored bytes as C++ object.
+   */
   virtual void build_store_ir__relocate(CodeBuilder &builder,
                                         llvm::Value *value,
                                         llvm::Value *address) const = 0;
+
+  /**
+   * Build code to copy the value to a specific memory address. The original value should stay the
+   * same.
+   *
+   * Usually, it should be possible to interpret the stored bytes as C++ object.
+   */
   virtual void build_store_ir__copy(CodeBuilder &builder,
                                     llvm::Value *value,
                                     llvm::Value *address) const = 0;
+
+  /**
+   * Build code to copy the value from a specific memory address into a llvm::Value. The stored
+   * value should not be changed.
+   */
   virtual llvm::Value *build_load_ir__copy(CodeBuilder &builder, llvm::Value *address) const = 0;
+
+  /**
+   * Build code to relocate the value froma specific memory address into a llvm::Value. The stored
+   * value should be freed in the process.
+   */
   virtual llvm::Value *build_load_ir__relocate(CodeBuilder &builder,
                                                llvm::Value *address) const = 0;
 };