Add comments about env-dependent APIs

Author: lutovich

src/v1/internal/browser/index.js

@@ -22,6 +22,17 @@ import WebSocketChannel from './browser-channel';
 import BrowserHosNameResolver from './browser-host-name-resolver';
 import utf8Codec from './browser-utf8';
 
+/*
+
+This module exports a set of components to be used in browser environment.
+They are not compatible with NodeJS environment.
+All files import/require APIs from `node/index.js` by default.
+Such imports are replaced at build time with `browser/index.js` when building a browser bundle.
+
+NOTE: exports in this module should have exactly the same names/structure as exports in `node/index.js`.
+
+ */
+
 export const alloc = arg => new HeapBuffer(arg);
 export const Channel = WebSocketChannel;
 export const HostNameResolver = BrowserHosNameResolver;

src/v1/internal/node/index.js

@@ -22,6 +22,17 @@ import NodeChannel from './node-channel';
 import NodeHostNameResolver from './node-host-name-resolver';
 import utf8Codec from './node-utf8';
 
+/*
+
+This module exports a set of components to be used in NodeJS environment.
+They are not compatible with browser environment.
+All files that require environment-dependent APIs should import this file by default.
+Imports/requires are replaced at build time with `browser/index.js` when building a browser bundle.
+
+NOTE: exports in this module should have exactly the same names/structure as exports in `browser/index.js`.
+
+ */
+
 export const alloc = arg => new NodeBuffer(arg);
 export const Channel = NodeChannel;
 export const HostNameResolver = NodeHostNameResolver;