From 55abf34be5f56d500cacd668fd9192ddd065c002 Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Wed, 11 Mar 2015 14:14:18 +0100 Subject: [PATCH] doc: don't use `using namespace v8` Wholesale importing an entire namespace with `using namespace` is a bad practice. Remove it from the addons documentation and replace it with proper `using` directives. Wrap code in a namespace while we are here. PR-URL: https://github.com/iojs/io.js/pull/1125 Reviewed-By: Rod Vagg Reviewed-By: Trevor Norris --- doc/api/addons.markdown | 156 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 145 insertions(+), 11 deletions(-) diff --git a/doc/api/addons.markdown b/doc/api/addons.markdown index 58e99e60f1566d..8a008c2977dc39 100644 --- a/doc/api/addons.markdown +++ b/doc/api/addons.markdown @@ -41,7 +41,15 @@ First we create a file `hello.cc`: // hello.cc #include - using namespace v8; + namespace demo { + + using v8::FunctionCallbackInfo; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Object; + using v8::String; + using v8::Value; void Method(const FunctionCallbackInfo& args) { Isolate* isolate = args.GetIsolate(); @@ -54,6 +62,8 @@ First we create a file `hello.cc`: NODE_MODULE(addon, init) + } // namespace demo + Note that all io.js addons must export an initialization function: void Initialize(Local exports); @@ -141,7 +151,17 @@ function calls and return a result. This is the main and only needed source // addon.cc #include - using namespace v8; + namespace demo { + + using v8::Exception; + using v8::FunctionCallbackInfo; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Number; + using v8::Object; + using v8::String; + using v8::Value; void Add(const FunctionCallbackInfo& args) { Isolate* isolate = args.GetIsolate(); @@ -170,6 +190,8 @@ function calls and return a result. This is the main and only needed source NODE_MODULE(addon, Init) + } // namespace demo + You can test it with the following JavaScript snippet: // test.js @@ -186,7 +208,16 @@ there. Here's `addon.cc`: // addon.cc #include - using namespace v8; + namespace demo { + + using v8::Function; + using v8::FunctionCallbackInfo; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Object; + using v8::String; + using v8::Value; void RunCallback(const FunctionCallbackInfo& args) { Isolate* isolate = args.GetIsolate(); @@ -202,6 +233,8 @@ there. Here's `addon.cc`: NODE_MODULE(addon, Init) + } // namespace demo + Note that this example uses a two-argument form of `Init()` that receives the full `module` object as the second argument. This allows the addon to completely overwrite `exports` with a single function instead of @@ -226,7 +259,15 @@ the string passed to `createObject()`: // addon.cc #include - using namespace v8; + namespace demo { + + using v8::FunctionCallbackInfo; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Object; + using v8::String; + using v8::Value; void CreateObject(const FunctionCallbackInfo& args) { Isolate* isolate = args.GetIsolate(); @@ -243,6 +284,8 @@ the string passed to `createObject()`: NODE_MODULE(addon, Init) + } // namespace demo + To test it in JavaScript: // test.js @@ -261,7 +304,17 @@ wraps a C++ function: // addon.cc #include - using namespace v8; + namespace demo { + + using v8::Function; + using v8::FunctionCallbackInfo; + using v8::FunctionTemplate; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Object; + using v8::String; + using v8::Value; void MyFunction(const FunctionCallbackInfo& args) { Isolate* isolate = args.GetIsolate(); @@ -286,6 +339,8 @@ wraps a C++ function: NODE_MODULE(addon, Init) + } // namespace demo + To test: // test.js @@ -305,7 +360,10 @@ module `addon.cc`: #include #include "myobject.h" - using namespace v8; + namespace demo { + + using v8::Local; + using v8::Object; void InitAll(Local exports) { MyObject::Init(exports); @@ -313,6 +371,8 @@ module `addon.cc`: NODE_MODULE(addon, InitAll) + } // namespace demo + Then in `myobject.h` make your wrapper inherit from `node::ObjectWrap`: // myobject.h @@ -322,6 +382,8 @@ Then in `myobject.h` make your wrapper inherit from `node::ObjectWrap`: #include #include + namespace demo { + class MyObject : public node::ObjectWrap { public: static void Init(v8::Local exports); @@ -336,6 +398,8 @@ Then in `myobject.h` make your wrapper inherit from `node::ObjectWrap`: double value_; }; + } // namespace demo + #endif And in `myobject.cc` implement the various methods that you want to expose. @@ -345,7 +409,19 @@ prototype: // myobject.cc #include "myobject.h" - using namespace v8; + namespace demo { + + using v8::Function; + using v8::FunctionCallbackInfo; + using v8::FunctionTemplate; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Number; + using v8::Object; + using v8::Persistent; + using v8::String; + using v8::Value; Persistent MyObject::constructor; @@ -398,6 +474,8 @@ prototype: args.GetReturnValue().Set(Number::New(isolate, obj->value_)); } + } // namespace demo + Test it with: // test.js @@ -423,7 +501,15 @@ Let's register our `createObject` method in `addon.cc`: #include #include "myobject.h" - using namespace v8; + namespace demo { + + using v8::FunctionCallbackInfo; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Object; + using v8::String; + using v8::Value; void CreateObject(const FunctionCallbackInfo& args) { MyObject::NewInstance(args); @@ -437,6 +523,8 @@ Let's register our `createObject` method in `addon.cc`: NODE_MODULE(addon, InitAll) + } // namespace demo + In `myobject.h` we now introduce the static method `NewInstance` that takes care of instantiating the object (i.e. it does the job of `new` in JavaScript): @@ -447,6 +535,8 @@ care of instantiating the object (i.e. it does the job of `new` in JavaScript): #include #include + namespace demo { + class MyObject : public node::ObjectWrap { public: static void Init(v8::Isolate* isolate); @@ -462,6 +552,8 @@ care of instantiating the object (i.e. it does the job of `new` in JavaScript): double value_; }; + } // namespace demo + #endif The implementation is similar to the above in `myobject.cc`: @@ -470,7 +562,19 @@ The implementation is similar to the above in `myobject.cc`: #include #include "myobject.h" - using namespace v8; + namespace demo { + + using v8::Function; + using v8::FunctionCallbackInfo; + using v8::FunctionTemplate; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Number; + using v8::Object; + using v8::Persistent; + using v8::String; + using v8::Value; Persistent MyObject::constructor; @@ -530,6 +634,8 @@ The implementation is similar to the above in `myobject.cc`: args.GetReturnValue().Set(Number::New(isolate, obj->value_)); } + } // namespace demo + Test it with: // test.js @@ -558,7 +664,16 @@ In the following `addon.cc` we introduce a function `add()` that can take on two #include #include "myobject.h" - using namespace v8; + namespace demo { + + using v8::FunctionCallbackInfo; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Number; + using v8::Object; + using v8::String; + using v8::Value; void CreateObject(const FunctionCallbackInfo& args) { MyObject::NewInstance(args); @@ -585,6 +700,8 @@ In the following `addon.cc` we introduce a function `add()` that can take on two NODE_MODULE(addon, InitAll) + } // namespace demo + To make things interesting we introduce a public method in `myobject.h` so we can probe private values after unwrapping the object: @@ -595,6 +712,8 @@ can probe private values after unwrapping the object: #include #include + namespace demo { + class MyObject : public node::ObjectWrap { public: static void Init(v8::Isolate* isolate); @@ -610,6 +729,8 @@ can probe private values after unwrapping the object: double value_; }; + } // namespace demo + #endif The implementation of `myobject.cc` is similar as before: @@ -618,7 +739,18 @@ The implementation of `myobject.cc` is similar as before: #include #include "myobject.h" - using namespace v8; + namespace demo { + + using v8::Function; + using v8::FunctionCallbackInfo; + using v8::FunctionTemplate; + using v8::HandleScope; + using v8::Isolate; + using v8::Local; + using v8::Object; + using v8::Persistent; + using v8::String; + using v8::Value; Persistent MyObject::constructor; @@ -666,6 +798,8 @@ The implementation of `myobject.cc` is similar as before: args.GetReturnValue().Set(instance); } + } // namespace demo + Test it with: // test.js