refactor(shared-utils): Improve readability and consistency in code c…

…omments (vuejs#8529)

Improvements that apply to all comments:
- Consistent use of periods
- Consistent use of commas
- Consistent capitalization
- Correct use of articles (a, an, the)

Improvements to specific comments:
- Correct pluralization in the description for helper functions
- Reword for clarity and break into shorter sentences the description
for `polyfillBind` function
- Reword for clarity the description for `genStaticKeys` function
- Add a previously missing description for `looseIndexOf` function

Fixes: vuejs#8528

src/shared/util.js

@@ -2,8 +2,8 @@
 
 export const emptyObject = Object.freeze({})
 
-// these helpers produces better vm code in JS engines due to their
-// explicitness and function inlining
+// These helpers produce better VM code in JS engines due to their
+// explicitness and function inlining.
 export function isUndef (v: any): boolean %checks {
  return v === undefined || v === null
 }
@@ -21,7 +21,7 @@ export function isFalse (v: any): boolean %checks {
 }
 
 /**
- * Check if value is primitive
+ * Check if value is primitive.
  */
 export function isPrimitive (value: any): boolean %checks {
  return (
@@ -43,7 +43,7 @@ export function isObject (obj: mixed): boolean %checks {
 }
 
 /**
- * Get the raw type string of a value e.g. [object Object]
+ * Get the raw type string of a value, e.g., [object Object].
  */
 const _toString = Object.prototype.toString
 
@@ -83,7 +83,7 @@ export function toString (val: any): string {
 }
 
 /**
- * Convert a input value to a number for persistence.
+ * Convert an input value to a number for persistence.
  * If the conversion fails, return original string.
  */
 export function toNumber (val: string): number | string {
@@ -115,12 +115,12 @@ export function makeMap (
 export const isBuiltInTag = makeMap('slot,component', true)
 
 /**
- * Check if a attribute is a reserved attribute.
+ * Check if an attribute is a reserved attribute.
  */
 export const isReservedAttribute = makeMap('key,ref,slot,slot-scope,is')
 
 /**
- * Remove an item from an array
+ * Remove an item from an array.
  */
 export function remove (arr: Array<any>, item: any): Array<any> | void {
  if (arr.length) {
@@ -132,7 +132,7 @@ export function remove (arr: Array<any>, item: any): Array<any> | void {
 }
 
 /**
- * Check whether the object has the property.
+ * Check whether an object has the property.
  */
 const hasOwnProperty = Object.prototype.hasOwnProperty
 export function hasOwn (obj: Object | Array<*>, key: string): boolean {
@@ -174,11 +174,11 @@ export const hyphenate = cached((str: string): string => {
 })
 
 /**
- * Simple bind polyfill for environments that do not support it... e.g.
- * PhantomJS 1.x. Technically we don't need this anymore since native bind is
- * now more performant in most browsers, but removing it would be breaking for
- * code that was able to run in PhantomJS 1.x, so this must be kept for
- * backwards compatibility.
+ * Simple bind polyfill for environments that do not support it,
+ * e.g., PhantomJS 1.x. Technically, we don't need this anymore
+ * since native bind is now performant enough in most browsers.
+ * But removing it would mean breaking code that was able to run in
+ * PhantomJS 1.x, so this must be kept for backward compatibility.
  */
 
 /* istanbul ignore next */
@@ -243,7 +243,7 @@ export function toObject (arr: Array<any>): Object {
 /**
  * Perform no operation.
  * Stubbing args to make Flow happy without leaving useless transpiled code
- * with ...rest (https://flow.org/blog/2017/05/07/Strict-Function-Call-Arity/)
+ * with ...rest (https://flow.org/blog/2017/05/07/Strict-Function-Call-Arity/).
  */
 export function noop (a?: any, b?: any, c?: any) {}
 
@@ -253,12 +253,12 @@ export function noop (a?: any, b?: any, c?: any) {}
 export const no = (a?: any, b?: any, c?: any) => false
 
 /**
- * Return same value
+ * Return the same value.
  */
 export const identity = (_: any) => _
 
 /**
- * Generate a static keys string from compiler modules.
+ * Generate a string containing static keys from compiler modules.
  */
 export function genStaticKeys (modules: Array<ModuleOptions>): string {
  return modules.reduce((keys, m) => {
@@ -303,6 +303,11 @@ export function looseEqual (a: any, b: any): boolean {
  }
 }
 
+/**
+ * Return the first index at which a loosely equal value can be
+ * found in the array (if value is a plain object, the array must
+ * contain an object of the same shape), or -1 if it is not present.
+ */
 export function looseIndexOf (arr: Array<mixed>, val: mixed): number {
  for (let i = 0; i < arr.length; i++) {
  if (looseEqual(arr[i], val)) return i