From d6a186a8f18c1b14979e0244c0434b5b89c0f8a9 Mon Sep 17 00:00:00 2001
From: Josh Haberman <jhaberman@gmail.com>
Date: Thu, 4 Feb 2016 14:58:45 -0800
Subject: Added some documentation in comments.

---
 js/commonjs/export.js                     |  3 +++
 js/commonjs/export_asserts.js             |  8 +++++++-
 js/commonjs/rewrite_tests_for_commonjs.js | 22 +++++++++++++++++++++-
 3 files changed, 31 insertions(+), 2 deletions(-)

(limited to 'js/commonjs')

diff --git a/js/commonjs/export.js b/js/commonjs/export.js
index ffbeb9db..89ded330 100644
--- a/js/commonjs/export.js
+++ b/js/commonjs/export.js
@@ -1,5 +1,8 @@
 /**
  * @fileoverview Export symbols needed by generated code in CommonJS style.
+ *
+ * This effectively is our canonical list of what we publicly export from
+ * the google-protobuf.js file that we build at distribution time.
  */
 
 exports.Message = jspb.Message;
diff --git a/js/commonjs/export_asserts.js b/js/commonjs/export_asserts.js
index 16abdd7d..9b823d3c 100644
--- a/js/commonjs/export_asserts.js
+++ b/js/commonjs/export_asserts.js
@@ -1,11 +1,17 @@
 /**
- * @fileoverview Description of this file.
+ * @fileoverview Exports symbols needed only by tests.
+ *
+ * This file exports several Closure Library symbols that are only
+ * used by tests.  It is used to generate a file
+ * closure_asserts_commonjs.js that is only used at testing time.
  */
 
 goog.require('goog.testing.asserts');
 
 var global = Function('return this')();
 
+// All of the closure "assert" functions are exported at the global level.
+//
 // The Google Closure assert functions start with assert, eg.
 //   assertThrows
 //   assertNotThrows
diff --git a/js/commonjs/rewrite_tests_for_commonjs.js b/js/commonjs/rewrite_tests_for_commonjs.js
index 4dc0a22d..d49f8a93 100644
--- a/js/commonjs/rewrite_tests_for_commonjs.js
+++ b/js/commonjs/rewrite_tests_for_commonjs.js
@@ -1,5 +1,25 @@
 /**
- * @fileoverview Description of this file.
+ * @fileoverview Utility to translate test files to CommonJS imports.
+ *
+ * This is a somewhat hacky tool designed to do one very specific thing.
+ * All of the test files in *_test.js are written with Closure-style
+ * imports (goog.require()).  This works great for running the tests
+ * against Closure-style generated code, but we also want to run the
+ * tests against CommonJS-style generated code without having to fork
+ * the tests.
+ *
+ * Closure-style imports import each individual type by name.  This is
+ * very different than CommonJS imports which are by file.  So we put
+ * special comments in these tests like:
+ *
+ * // CommonJS-LoadFromFile: test_pb
+ * goog.require('proto.jspb.test.CloneExtension');
+ * goog.require('proto.jspb.test.Complex');
+ * goog.require('proto.jspb.test.DefaultValues');
+ *
+ * This script parses that special comment and uses it to generate proper
+ * CommonJS require() statements so that the tests can run and pass using
+ * CommonJS imports.
  */
 
 var lineReader = require('readline').createInterface({
-- 
cgit v1.2.3