src: fix comments re PER_ISOLATE macros

PR-URL: nodejs#12899
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James Snell <jasnell@gmail.com>

src/env-inl.h

@@ -36,7 +36,10 @@
 
 namespace node {
 
-// Create string properties as internalized one byte strings.
+inline IsolateData::IsolateData(v8::Isolate* isolate, uv_loop_t* event_loop,
+                                uint32_t* zero_fill_field) :
+
+// Create string and private symbol properties as internalized one byte strings.
 //
 // Internalized because it makes property lookups a little faster and because
 // the string is created in the old space straight away.  It's going to end up
@@ -45,9 +48,6 @@ namespace node {
 //
 // One byte because our strings are ASCII and we can safely skip V8's UTF-8
 // decoding step.  It's a one-time cost, but why pay it when you don't have to?
-inline IsolateData::IsolateData(v8::Isolate* isolate, uv_loop_t* event_loop,
-                                uint32_t* zero_fill_field)
-    :
 #define V(PropertyName, StringValue)                                          \
     PropertyName ## _(                                                        \
         isolate,                                                              \

src/env.h

@@ -40,14 +40,6 @@
 #include <stdint.h>
 #include <vector>
 
-// Caveat emptor: we're going slightly crazy with macros here but the end
-// hopefully justifies the means. We have a lot of per-context properties
-// and adding and maintaining their getters and setters by hand would be
-// a nightmare so let's make the preprocessor generate them for us.
-//
-// Make sure that any macros defined here are undefined again at the bottom
-// of context-inl.h. The exceptions are NODE_CONTEXT_EMBEDDER_DATA_INDEX
-// and NODE_ISOLATE_SLOT, they may have been defined externally.
 namespace node {
 
 // Pick an index that's hopefully out of the way when we're embedded inside
@@ -64,6 +56,17 @@ namespace node {
 #define NODE_PUSH_VAL_TO_ARRAY_MAX 8
 #endif
 
+// PER_ISOLATE_* macros: We have a lot of per-isolate properties
+// and adding and maintaining their getters and setters by hand would be
+// difficult so let's make the preprocessor generate them for us.
+//
+// In each macro, `V` is expected to be the name of a macro or function which
+// accepts the number of arguments provided in each tuple in the macro body,
+// typically two. The named function will be invoked against each tuple.
+//
+// Make sure that any macro V defined for use with the PER_ISOLATE_* macros is
+// undefined again after use.
+
 // Private symbols are per-isolate primitives but Environment proxies them
 // for the sake of convenience.  Strings should be ASCII-only and have a
 // "node:" prefix to avoid name clashes with third-party code.