add ES comments for StringIterator

Huxpro · facebook-github-bot · commit a192ca486bf0 · 2020-07-27T19:02:10.000-07:00
Summary:
This diff adds some missing ECMA-262 section comments for
StringIterator related functions to guide code readers.

Reviewed By: avp

Differential Revision: D22396644

fbshipit-source-id: d6fd9185abc2ca44f4d4cefdd9757f6128314f32
diff --git a/include/hermes/VM/PrimitiveBox.h b/include/hermes/VM/PrimitiveBox.h
@@ -158,6 +158,7 @@ class JSString final : public PrimitiveBox {
 };
 
 /// StringIterator object.
+/// See ES6 21.1.5.3 for Properties of String Iterator Instances.
 class JSStringIterator : public JSObject {
   using Super = JSObject;
 
diff --git a/lib/VM/JSLib/String.cpp b/lib/VM/JSLib/String.cpp
@@ -1216,20 +1216,25 @@ stringPrototypeRepeat(void *, Runtime *runtime, NativeArgs args) {
   return builderRes->getStringPrimitive().getHermesValue();
 }
 
+/// ES6.0 21.1.3.27 String.prototype [ @@iterator ]( )
 CallResult<HermesValue>
 stringPrototypeSymbolIterator(void *, Runtime *runtime, NativeArgs args) {
+  // 1. Let O be RequireObjectCoercible(this value).
   auto thisValue = args.getThisHandle();
   if (LLVM_UNLIKELY(
           checkObjectCoercible(runtime, thisValue) ==
           ExecutionStatus::EXCEPTION)) {
     return ExecutionStatus::EXCEPTION;
   }
+  // 2. Let S be ToString(O).
+  // 3. ReturnIfAbrupt(S).
   auto strRes = toString_RJS(runtime, thisValue);
   if (LLVM_UNLIKELY(strRes == ExecutionStatus::EXCEPTION)) {
     return ExecutionStatus::EXCEPTION;
   }
   auto string = runtime->makeHandle(std::move(*strRes));
 
+  // 4. Return CreateStringIterator(S).
   return JSStringIterator::create(runtime, string);
 }
 
diff --git a/lib/VM/JSLib/StringIterator.cpp b/lib/VM/JSLib/StringIterator.cpp
@@ -40,8 +40,13 @@ void populateStringIteratorPrototype(Runtime *runtime) {
       dpf);
 }
 
+/// ES6.0 21.1.5.2.1 %StringIteratorPrototype%.next ( ) 1-3
 CallResult<HermesValue>
 stringIteratorPrototypeNext(void *, Runtime *runtime, NativeArgs args) {
+  // 1. Let O be the this value.
+  // 2. If Type(O) is not Object, throw a TypeError exception.
+  // 3. If O does not have all of the internal slots of a String Iterator
+  // Instance (21.1.5.3), throw a TypeError exception.
   auto O = args.dyncastThis<JSStringIterator>();
   if (LLVM_UNLIKELY(!O)) {
     return runtime->raiseTypeError(
diff --git a/lib/VM/PrimitiveBox.cpp b/lib/VM/PrimitiveBox.cpp
@@ -236,6 +236,7 @@ void StringIteratorDeserialize(Deserializer &d, CellKind kind) {
 }
 #endif
 
+/// ES6.0 21.1.5.1 CreateStringIterator Abstract Operation
 CallResult<HermesValue> JSStringIterator::create(
     Runtime *runtime,
     Handle<StringPrimitive> string) {
@@ -251,6 +252,7 @@ CallResult<HermesValue> JSStringIterator::create(
       *string));
 }
 
+/// ES6.0 21.1.5.2.1 %StringIteratorPrototype%.next ( ) 4-14
 CallResult<HermesValue> JSStringIterator::nextElement(
     Handle<JSStringIterator> self,
     Runtime *runtime) {

Original file line number	Diff line number	Diff line change
`@@ -1216,20 +1216,25 @@ stringPrototypeRepeat(void , Runtime runtime, NativeArgs args) {`
`1216`	`1216`	`return builderRes->getStringPrimitive().getHermesValue();`
`1217`	`1217`	`}`
`1218`	`1218`
	`1219`	`+/// ES6.0 21.1.3.27 String.prototype [ @@iterator ]( )`
`1219`	`1220`	`CallResult<HermesValue>`
`1220`	`1221`	`stringPrototypeSymbolIterator(void , Runtime runtime, NativeArgs args) {`
	`1222`	`+ // 1. Let O be RequireObjectCoercible(this value).`
`1221`	`1223`	`auto thisValue = args.getThisHandle();`
`1222`	`1224`	`if (LLVM_UNLIKELY(`
`1223`	`1225`	`checkObjectCoercible(runtime, thisValue) ==`
`1224`	`1226`	`ExecutionStatus::EXCEPTION)) {`
`1225`	`1227`	`return ExecutionStatus::EXCEPTION;`
`1226`	`1228`	`}`
	`1229`	`+ // 2. Let S be ToString(O).`
	`1230`	`+ // 3. ReturnIfAbrupt(S).`
`1227`	`1231`	`auto strRes = toString_RJS(runtime, thisValue);`
`1228`	`1232`	`if (LLVM_UNLIKELY(strRes == ExecutionStatus::EXCEPTION)) {`
`1229`	`1233`	`return ExecutionStatus::EXCEPTION;`
`1230`	`1234`	`}`
`1231`	`1235`	`auto string = runtime->makeHandle(std::move(*strRes));`
`1232`	`1236`
	`1237`	`+ // 4. Return CreateStringIterator(S).`
`1233`	`1238`	`return JSStringIterator::create(runtime, string);`
`1234`	`1239`	`}`
`1235`	`1240`
Original file line number	Diff line number	Diff line change
`@@ -236,6 +236,7 @@ void StringIteratorDeserialize(Deserializer &d, CellKind kind) {`
`236`	`236`	`}`
`237`	`237`	`#endif`
`238`	`238`
	`239`	`+/// ES6.0 21.1.5.1 CreateStringIterator Abstract Operation`
`239`	`240`	`CallResult<HermesValue> JSStringIterator::create(`
`240`	`241`	`Runtime *runtime,`
`241`	`242`	`Handle<StringPrimitive> string) {`
`@@ -251,6 +252,7 @@ CallResult<HermesValue> JSStringIterator::create(`
`251`	`252`	`*string));`
`252`	`253`	`}`
`253`	`254`
	`255`	`+/// ES6.0 21.1.5.2.1 %StringIteratorPrototype%.next ( ) 4-14`
`254`	`256`	`CallResult<HermesValue> JSStringIterator::nextElement(`
`255`	`257`	`Handle<JSStringIterator> self,`
`256`	`258`	`Runtime *runtime) {`