meta: better doc, minor changes to propagate the context to the meta handles

src/entt/meta/meta.hpp

@@ -968,8 +968,8 @@ struct meta_func {
      * function.
      *
      * @warning
-     * The context of instances and arguments is not changed.<br/>
-     * Therefore, it's up to the caller to wrap any objects correctly.
+     * The context of the arguments is **not** changed.<br/>
+     * It's up to the caller to bind them to the right context(s).
      *
      * @param instance An opaque instance of the underlying type.
      * @param args Parameters to use to invoke the function.
@@ -977,7 +977,7 @@ struct meta_func {
      * @return A wrapper containing the returned value, if any.
      */
     meta_any invoke(meta_handle instance, meta_any *const args, const size_type sz) const {
-        return sz == arity() ? node->invoke(*ctx, std::move(instance), args) : meta_any{meta_ctx_arg, *ctx};
+        return sz == arity() ? node->invoke(*ctx, meta_handle{*ctx, std::move(instance)}, args) : meta_any{meta_ctx_arg, *ctx};
     }
 
     /**
@@ -1343,8 +1343,8 @@ public:
      * If suitable, the implicitly generated default constructor is used.
      *
      * @warning
-     * The context of instances and arguments is not changed.<br/>
-     * Therefore, it's up to the caller to wrap any objects correctly.
+     * The context of the arguments is **not** changed.<br/>
+     * It's up to the caller to bind them to the right context(s).
      *
      * @param args Parameters to use to construct the instance.
      * @param sz Number of parameters to use to construct the instance.
@@ -1397,8 +1397,8 @@ public:
      * function.
      *
      * @warning
-     * The context of instances and arguments is not changed.<br/>
-     * Therefore, it's up to the caller to wrap any objects correctly.
+     * The context of the arguments is **not** changed.<br/>
+     * It's up to the caller to bind them to the right context(s).
      *
      * @param id Unique identifier.
      * @param instance An opaque instance of the underlying type.
@@ -1410,7 +1410,7 @@ public:
         if(node.details) {
             if(auto it = node.details->func.find(id); it != node.details->func.cend()) {
                 if(const auto *candidate = lookup(args, sz, (instance->data() == nullptr), [curr = &it->second]() mutable { return curr ? std::exchange(curr, curr->next.get()) : nullptr; }); candidate) {
-                    return candidate->invoke(*ctx, std::move(instance), args);
+                    return candidate->invoke(*ctx, meta_handle{*ctx, std::move(instance)}, args);
                 }
             }
         }

src/entt/meta/utility.hpp

@@ -213,11 +213,6 @@ template<typename Type>
 
 /**
  * @brief Sets the value of a given variable.
- *
- * @warning
- * The context of instances and arguments is not changed.<br/>
- * Therefore, it's up to the caller to wrap any objects correctly.
- *
  * @tparam Type Reflected type to which the variable is associated.
  * @tparam Data The actual variable to set.
  * @param instance An opaque instance of the underlying type, if required.
@@ -263,8 +258,8 @@ template<typename Type, auto Data>
  * @brief Gets the value of a given variable.
  *
  * @warning
- * The context of instances and arguments is not changed.<br/>
- * Therefore, it's up to the caller to wrap any objects correctly.
+ * The context provided is used only for the return type.<br/>
+ * It's up to the caller to bind the arguments to the right context(s).
  *
  * @tparam Type Reflected type to which the variable is associated.
  * @tparam Data The actual variable to get.
@@ -373,8 +368,8 @@ template<typename Type, typename... Args, std::size_t... Index>
  * @brief Tries to _invoke_ an object given a list of erased parameters.
  *
  * @warning
- * The context of instances and arguments is not changed.<br/>
- * Therefore, it's up to the caller to wrap any objects correctly.
+ * The context provided is used only for the return type.<br/>
+ * It's up to the caller to bind the arguments to the right context(s).
  *
  * @tparam Type Reflected type to which the object to _invoke_ is associated.
  * @tparam Policy Optional policy (no policy set by default).
@@ -409,8 +404,8 @@ template<typename Type, typename Policy = as_is_t, typename Candidate>
  * @brief Tries to invoke a function given a list of erased parameters.
  *
  * @warning
- * The context of instances and arguments is not changed.<br/>
- * Therefore, it's up to the caller to wrap any objects correctly.
+ * The context provided is used only for the return type.<br/>
+ * It's up to the caller to bind the arguments to the right context(s).
  *
  * @tparam Type Reflected type to which the function is associated.
  * @tparam Candidate The actual function to invoke.
@@ -443,8 +438,8 @@ template<typename Type, auto Candidate, typename Policy = as_is_t>
  * @brief Tries to construct an instance given a list of erased parameters.
  *
  * @warning
- * The context of instances and arguments is not changed.<br/>
- * Therefore, it's up to the caller to wrap any objects correctly.
+ * The context provided is used only for the return type.<br/>
+ * It's up to the caller to bind the arguments to the right context(s).
  *
  * @tparam Type Actual type of the instance to construct.
  * @tparam Args Types of arguments expected.
@@ -473,8 +468,8 @@ template<typename Type, typename... Args>
  * @brief Tries to construct an instance given a list of erased parameters.
  *
  * @warning
- * The context of instances and arguments is not changed.<br/>
- * Therefore, it's up to the caller to wrap any objects correctly.
+ * The context provided is used only for the return type.<br/>
+ * It's up to the caller to bind the arguments to the right context(s).
  *
  * @tparam Type Reflected type to which the object to _invoke_ is associated.
  * @tparam Policy Optional policy (no policy set by default).
@@ -511,8 +506,8 @@ template<typename Type, typename Policy = as_is_t, typename Candidate>
  * @brief Tries to construct an instance given a list of erased parameters.
  *
  * @warning
- * The context of instances and arguments is not changed.<br/>
- * Therefore, it's up to the caller to wrap any objects correctly.
+ * The context provided is used only for the return type.<br/>
+ * It's up to the caller to bind the arguments to the right context(s).
  *
  * @tparam Type Reflected type to which the function is associated.
  * @tparam Candidate The actual function to invoke.