Merge 81006c1 into 9be4ff1

backend/V8/V8Helper.cc

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 
+#include "V8Helper.hpp"
 #include "V8Engine.h"
 
 namespace script::v8_backend {

backend/V8/V8Helper.hpp

@@ -20,6 +20,7 @@
 #include <utility>
 #include "../../src/utils/Helper.hpp"
 #include "V8Engine.h"
+#include "V8Reference.hpp"
 
 namespace script::v8_backend {
 

backend/V8/V8Value.cc

@@ -19,7 +19,6 @@
 #include "../../src/Reference.h"
 #include "../../src/Utils.h"
 #include "V8Engine.h"
-#include "V8Helper.h"
 #include "V8Helper.hpp"
 
 namespace script {

docs/en/NativeBinding.md

@@ -188,6 +188,10 @@ So when you hold a ScriptClass pointer in C++, you may find that `ScriptClass::g
 #### `ScriptClass::ScriptClass(ConstructFromCpp<T>)`
 This is another constructor of ScriptClass. The usage scenario is that a certain binding class requires a lot of C++ dependencies when constructing it. In this way, going through another ScriptX will cause a lot of type conversion and troublesome. So provide this constructor, directly use C++new as an instance, and then get the corresponding ScriptObject through `getScriptObejct` and return it to ScriptX.
 
+Please use this competence with extra CAUTION, read the doc in header file with care, otherwise you may face strange crashes (memory issue).
+
+YOU HAVE BEEN WARNED.
+
 ```c++
 
 class MyImage: public script::ScriptClass {

docs/zh/NativeBinding.md

@@ -176,6 +176,8 @@ ScriptX不保证这个实例一定是在 ScriptObject GC的同时销毁（可能
 #### `ScriptClass::ScriptClass(ConstructFromCpp<T>)`
 这个是ScriptClass的另一个构造函数，使用场景是某个绑定类构造时需要很多C++依赖，这样再经过一道ScriptX就导致类型转换很多很麻烦。所以提供这个构造函数，直接用C++new一个实例出来，然后通过 `getScriptObejct` 拿到对应的ScriptObject返回给ScriptX。
 
+请谨慎使用这个能力，并详细阅读头文件中的相关注释，否则你将面临内存问题导致的crash！
+
 ```c++
 
 class MyImage : public script::ScriptClass {

src/Native.h

@@ -112,38 +112,61 @@ class ScriptClass {
   struct ConstructFromCpp {};
 
   /**
-   * This constructor is be used pure to create a ScriptObject along with
+   * This constructor is been used purely to create a ScriptObject along with
    * it's script object with cpp code (not from the script constructor binding).
    *
+   * Please use this competence with extra CAUTION, read the following doc with care,
+   * otherwise you may face strange crashes (memory issue).
+   *
+   * YOU HAVE BEEN WARNED.
+   *
+   *
    * use case:
    *
    * \code
    *
-   * class MyContextScriptObject : public ScriptObject {
+   * class Context : public ScriptObject {
    * public:
-   *     MyContextScriptObject(Canvas* canvas) :
-   *        ScriptObject(ConstructFromCpp<MyContextScriptObject>()) {
+   *     Context(Canvas* canvas) :
+   *        ScriptObject(ConstructFromCpp<Context>()) {
    *            // pay attention, in constructor the `this` is partial inited,
    *            // take care of publishing `this` pointer and/or script object.
    *        }
    * };
    *
    * Canvas* canvas = render->getCanvas();
-   * // note: the pointer is managed be script object
+   *
+   * // NOTE: the pointer is managed be script object
    * // so, just return the script object out, it's all done.
-   * auto pointer = new MyContextScriptObject(canvas);
+   * auto pointer = new Context(canvas);
    * engine->set("context", pointer->getScriptObject());
-   * // never delete pointer, ScriptEngine does that on finalization.
+   * // NEVER delete the pointer, ScriptEngine does that on finalization.
+   * // AND NEVER keep the pointer from c++, still, it's managed by ScriptEngine,
+   * // use a global reference instead.
    *
    * \endcode
    *
-   * note: upon new, the returned pointer should be own(managed) by the script object,
+   *
+   * another use case:
+   *
+   * \code
+   *
+   * auto getContext = Function::newFunction([]() {
+   *   Canvas* canvas = render->getCanvas();
+   *   auto pointer = new Context(canvas);
+   *   return pointer->getScriptObject();
+   * });
+   *
+   * \endcode
+   *
+   * NOTE: upon new, the returned pointer should be own(managed) by the script object,
    * caller should not delete the pointer.
    *
-   * note: this constructor MUST be called under EngineScope.
+   * NOTE: this constructor MUST be called under EngineScope.
    *
-   * note: this ctor "CAN BE" implemented with no params, but which makes it the "default
-   * constructor" however, there are heavy logic inside this ctor, we deliberately add a param.
+   * NOTE: this ctor "CAN BE" implemented with no params, but which makes it the "default
+   * constructor" however, there is heavy logic inside this ctor, we deliberately add a param --
+   * policy.
    */
   template <typename T>
   explicit ScriptClass(ConstructFromCpp<T> policy);