add comments to explain the changed interface for unit test utility functions

Author: ckeshava

src/ripple/rpc/handlers/Submit.cpp

@@ -42,7 +42,7 @@ getFailHard(RPC::JsonContext const& context)
 
 // This is helper function that is used to calculate the CheckID field in a
 // CheckCreate transaction.
-// The function returns false, if an error occurs in the parsing of the input
+// The function returns false, if an error occurs whilst parsing the input
 // transaction.
 // Otherwise, true is returned and appropriate CheckID is populated in the
 // response
@@ -65,7 +65,7 @@ populateCheckID(
         return false;
     }
 
-    if(result[jss::engine_result] == "tesSUCCESS")
+    if (result[jss::engine_result] == "tesSUCCESS")
         result[jss::CheckID] = to_string(keylet::check(*acctID, seq).key);
 
     return true;

src/test/app/Check_test.cpp

@@ -257,7 +257,9 @@ class Check_test : public beast::unit_test::suite
         // CheckID must be returned upon successful creation of a Check object
         BEAST_EXPECT(jr.has_value());
         BEAST_EXPECT((*jr)["result"].isMember(jss::CheckID));
-        BEAST_EXPECT((*jr)["result"][jss::CheckID] == "DE86D4F9A732A12247B774C34175B3DD0E51D4D7407A34F67ADA2C398359289F");
+        BEAST_EXPECT(
+            (*jr)["result"][jss::CheckID] ==
+            "DE86D4F9A732A12247B774C34175B3DD0E51D4D7407A34F67ADA2C398359289F");
 
         env(check::create(alice, bob, USD(50)), source_tag(2));
         env.close();

src/test/jtx/Env.h

@@ -498,6 +498,9 @@ class Env
 
     /** Submit an existing JTx.
         This calls postconditions.
+
+        If the input is parsed successfully, then the RPC response is returned.
+        Otherwise, the return value optional is not set
     */
     virtual std::optional<Json::Value>
     submit(JTx const& jt);
@@ -514,7 +517,8 @@ class Env
     void
     postconditions(JTx const& jt, TER ter, bool didApply);
 
-    /** Apply funclets and submit. */
+    /** Apply funclets and submit. If the RPC command is sucessful, the
+     * response is returned.*/
     /** @{ */
     template <class JsonValue, class... FN>
     std::optional<Json::Value>