From 05953b3b83a35bacd013ab2c14088bdc1a5ebffd Mon Sep 17 00:00:00 2001
From: Kara Erickson <karakara@google.com>
Date: Wed, 13 Dec 2017 11:00:28 -0800
Subject: [PATCH] docs(core): add comments to assert functions (#20855)

PR Close #20855
---
 packages/core/src/render3/assert.ts | 53 +++++++++++++++++++++--------
 1 file changed, 39 insertions(+), 14 deletions(-)

diff --git a/packages/core/src/render3/assert.ts b/packages/core/src/render3/assert.ts
index 1227347bea..15f8776f67 100644
--- a/packages/core/src/render3/assert.ts
+++ b/packages/core/src/render3/assert.ts
@@ -6,34 +6,59 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-function stringify(value: any) {
+/**
+ * The functions in this file verify that the assumptions we are making
+ * about state in an instruction are correct before implementing any logic.
+ * They are meant only to be called in dev mode as sanity checks.
+ */
+
+/**
+ * Stringifies values such that strings are wrapped in explicit quotation marks and
+ * other types are stringified normally. Used in error messages (e.g. assertThrow)
+ * to make it clear that certain values are of the string type when comparing.
+ *
+ * e.g. `expected "3" to be 3` is easier to understand than `expected 3 to be 3`.
+ *
+ * @param {any} value - The value to be stringified
+ * @returns {string} the stringified value
+ */
+function stringifyValueForError(value: any): string {
   return typeof value === 'string' ? `"${value}"` : '' + value;
 }
 
-export function assertNumber(actual: any, condition: string) {
-  (typeof actual != 'number') && assertThrow(actual, 'number', condition, 'typeof ==');
+export function assertNumber(actual: any, name: string) {
+  (typeof actual != 'number') && assertThrow(actual, 'number', name, 'typeofr ==');
 }
 
 export function assertEqual<T>(
-    actual: T, expected: T, condition: string, serializer?: ((v: T) => string)) {
-  (actual != expected) && assertThrow(actual, expected, condition, '==', serializer);
+    actual: T, expected: T, name: string, serializer?: ((v: T) => string)) {
+  (actual != expected) && assertThrow(actual, expected, name, '==', serializer);
 }
 
-export function assertLessThan<T>(actual: T, expected: T, condition: string) {
-  (actual < expected) && assertThrow(actual, expected, condition, '>');
+export function assertLessThan<T>(actual: T, expected: T, name: string) {
+  (actual < expected) && assertThrow(actual, expected, name, '>');
 }
 
-export function assertNotNull<T>(actual: T, condition: string) {
-  assertNotEqual(actual, null, condition);
+export function assertNotNull<T>(actual: T, name: string) {
+  assertNotEqual(actual, null, name);
 }
 
-export function assertNotEqual<T>(actual: T, expected: T, condition: string) {
-  (actual == expected) && assertThrow(actual, expected, condition, '!=');
+export function assertNotEqual<T>(actual: T, expected: T, name: string) {
+  (actual == expected) && assertThrow(actual, expected, name, '!=');
 }
 
+/**
+ * Throws an error with a message constructed from the arguments.
+ *
+ * @param {T} actual - The actual value (e.g. 3)
+ * @param {T} expected - The expected value (e.g. 5)
+ * @param {string} name - The name of the value being checked (e.g. attrs.length)
+ * @param {string} operator - The comparison operator (e.g. <, >, ==)
+ * @param {(v: T) => string)} serializer - Function that maps a value to its display value
+ */
 export function assertThrow<T>(
-    actual: T, expected: T, condition: string, operator: string,
-    serializer: ((v: T) => string) = stringify) {
+    actual: T, expected: T, name: string, operator: string,
+    serializer: ((v: T) => string) = stringifyValueForError): never {
   throw new Error(
-      `ASSERT: expected ${condition} ${operator} ${serializer(expected)} but was ${serializer(actual)}!`);
+      `ASSERT: expected ${name} ${operator} ${serializer(expected)} but was ${serializer(actual)}!`);
 }