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

Ref T92709

source/blender/functions/FN_field.hh

@@ -405,6 +405,24 @@ class FieldEvaluator : NonMovable, NonCopyable {
   IndexMask get_evaluated_as_mask(const int field_index);
 };
 
+/**
+ * Evaluate fields in the given context. If possible, multiple fields should be evaluated together,
+ * because that can be more efficient when they share common sub-fields.
+ *
+ * \param scope: The resource scope that owns data that makes up the output virtual arrays. Make
+ *   sure the scope is not destructed when the output virtual arrays are still used.
+ * \param fields_to_evaluate: The fields that should be evaluated together.
+ * \param mask: Determines which indices are computed. The mask may be referenced by the returned
+ *   virtual arrays. So the underlying indices (if applicable) should live longer then #scope.
+ * \param context: The context that the field is evaluated in. Used to retrieve data from each
+ *   #FieldInput in the field network.
+ * \param dst_varrays: If provided, the computed data will be written into those virtual arrays
+ *   instead of into newly created ones. That allows making the computed data live longer than
+ *   #scope and is more efficient when the data will be written into those virtual arrays
+ *   later anyway.
+ * \return The computed virtual arrays for each provided field. If #dst_varrays is passed, the
+ *   provided virtual arrays are returned.
+ */
 Vector<GVArray> evaluate_fields(ResourceScope &scope,
                                 Span<GFieldRef> fields_to_evaluate,
                                 IndexMask mask,
@@ -434,6 +452,15 @@ template<typename T> Field<T> make_constant_field(T value)
 
 GField make_constant_field(const CPPType &type, const void *value);
 
+/**
+ * If the field depends on some input, the same field is returned.
+ * Otherwise the field is evaluated and a new field is created that just computes this constant.
+ *
+ * Making the field constant has two benefits:
+ * - The field-tree becomes a single node, which is more efficient when the field is evaluated many
+ *   times.
+ * - Memory of the input fields may be freed.
+ */
 GField make_field_constant_if_possible(GField field);
 
 class IndexFieldInput final : public FieldInput {

source/blender/functions/FN_generic_virtual_array.hh

@@ -148,11 +148,29 @@ class GVArrayCommon {
   void materialize_to_uninitialized(void *dst) const;
   void materialize_to_uninitialized(const IndexMask mask, void *dst) const;
 
+  /**
+   * Returns true when the virtual array is stored as a span internally.
+   */
   bool is_span() const;
+  /**
+   * Returns the internally used span of the virtual array. This invokes undefined behavior is the
+   * virtual array is not stored as a span internally.
+   */
   GSpan get_internal_span() const;
 
+  /**
+   * Returns true when the virtual array returns the same value for every index.
+   */
   bool is_single() const;
+  /**
+   * Copies the value that is used for every element into `r_value`, which is expected to point to
+   * initialized memory. This invokes undefined behavior if the virtual array would not return the
+   * same value for every index.
+   */
   void get_internal_single(void *r_value) const;
+  /**
+   * Same as `get_internal_single`, but `r_value` points to initialized memory.
+   */
   void get_internal_single_to_uninitialized(void *r_value) const;
 
   void get(const int64_t index, void *r_value) const;
@@ -226,6 +244,9 @@ class GVMutableArray : public GVArrayCommon {
   void set_by_relocate(const int64_t index, void *value);
 
   void fill(const void *value);
+  /**
+   * Copy the values from the source buffer to all elements in the virtual array.
+   */
   void set_all(const void *src);
 
   GVMutableArrayImpl *get_implementation() const;

source/blender/functions/FN_multi_function.hh

@@ -60,6 +60,12 @@ class MultiFunction {
   {
   }
 
+  /**
+   * The result is the same as using #call directly but this method has some additional features.
+   * - Automatic multi-threading when possible and appropriate.
+   * - Automatic index mask offsetting to avoid large temporary intermediate arrays that are mostly
+   *   unused.
+   */
   void call_auto(IndexMask mask, MFParams params, MFContext context) const;
   virtual void call(IndexMask mask, MFParams params, MFContext context) const = 0;
 

source/blender/functions/intern/field.cc

@@ -257,24 +257,6 @@ static void build_multi_function_procedure_for_fields(MFProcedure &procedure,
   BLI_assert(procedure.validate());
 }
 
-/**
- * Evaluate fields in the given context. If possible, multiple fields should be evaluated together,
- * because that can be more efficient when they share common sub-fields.
- *
- * \param scope: The resource scope that owns data that makes up the output virtual arrays. Make
- *   sure the scope is not destructed when the output virtual arrays are still used.
- * \param fields_to_evaluate: The fields that should be evaluated together.
- * \param mask: Determines which indices are computed. The mask may be referenced by the returned
- *   virtual arrays. So the underlying indices (if applicable) should live longer then #scope.
- * \param context: The context that the field is evaluated in. Used to retrieve data from each
- *   #FieldInput in the field network.
- * \param dst_varrays: If provided, the computed data will be written into those virtual arrays
- *   instead of into newly created ones. That allows making the computed data live longer than
- *   #scope and is more efficient when the data will be written into those virtual arrays
- *   later anyway.
- * \return The computed virtual arrays for each provided field. If #dst_varrays is passed, the
- *   provided virtual arrays are returned.
- */
 Vector<GVArray> evaluate_fields(ResourceScope &scope,
                                 Span<GFieldRef> fields_to_evaluate,
                                 IndexMask mask,
@@ -488,15 +470,6 @@ void evaluate_constant_field(const GField &field, void *r_value)
   varrays[0].get_to_uninitialized(0, r_value);
 }
 
-/**
- * If the field depends on some input, the same field is returned.
- * Otherwise the field is evaluated and a new field is created that just computes this constant.
- *
- * Making the field constant has two benefits:
- * - The field-tree becomes a single node, which is more efficient when the field is evaluated many
- *   times.
- * - Memory of the input fields may be freed.
- */
 GField make_field_constant_if_possible(GField field)
 {
   if (field.node().depends_on_input()) {

source/blender/functions/intern/generic_virtual_array.cc

@@ -547,36 +547,28 @@ void GVArrayCommon::move_from(GVArrayCommon &&other) noexcept
   other.impl_ = nullptr;
 }
 
-/* Returns true when the virtual array is stored as a span internally. */
 bool GVArrayCommon::is_span() const
 {
   return impl_->is_span();
 }
 
-/* Returns the internally used span of the virtual array. This invokes undefined behavior is the
- * virtual array is not stored as a span internally. */
 GSpan GVArrayCommon::get_internal_span() const
 {
   BLI_assert(this->is_span());
   return impl_->get_internal_span();
 }
 
-/* Returns true when the virtual array returns the same value for every index. */
 bool GVArrayCommon::is_single() const
 {
   return impl_->is_single();
 }
 
-/* Copies the value that is used for every element into `r_value`, which is expected to point to
- * initialized memory. This invokes undefined behavior if the virtual array would not return the
- * same value for every index. */
 void GVArrayCommon::get_internal_single(void *r_value) const
 {
   BLI_assert(this->is_single());
   impl_->get_internal_single(r_value);
 }
 
-/* Same as `get_internal_single`, but `r_value` points to initialized memory. */
 void GVArrayCommon::get_internal_single_to_uninitialized(void *r_value) const
 {
   impl_->type().default_construct(r_value);
@@ -729,7 +721,6 @@ GVMutableArrayImpl *GVMutableArray::get_implementation() const
   return this->get_impl();
 }
 
-/* Copy the values from the source buffer to all elements in the virtual array. */
 void GVMutableArray::set_all(const void *src)
 {
   this->get_impl()->set_all(src);

source/blender/functions/intern/multi_function.cc

@@ -66,12 +66,6 @@ static int64_t compute_grain_size(const ExecutionHints &hints, const IndexMask m
   return grain_size;
 }
 
-/**
- * The result is the same as using #call directly but this method has some additional features.
- * - Automatic multi-threading when possible and appropriate.
- * - Automatic index mask offsetting to avoid large temporary intermediate arrays that are mostly
- *   unused.
- */
 void MultiFunction::call_auto(IndexMask mask, MFParams params, MFContext context) const
 {
   if (mask.is_empty()) {