[skip ci] improved explanation of with_return_raw_result

Author: nikeethr

packages/bundled_models/persistence/src/persistence/interface/types.py

@@ -39,14 +39,46 @@ def __init__(
         """
         self.raw_type = PetInputDataType.UNKNOWN
         self.ds = self.from_arrlike(arraylike, dummy_varname, dimnames)
-        self.return_raw_result = False
+        self.return_raw_result = True
 
-    def with_return_raw_result(self, return_raw_result=bool):
+    def with_return_raw_result(self, return_raw_result: bool = True):
         """
         Optionally set this to return raw array from `map_each_var`
 
-        NOTE: this is a special purpose function. It is currently UNUSED, but
-        may be useful in some rare circumstances where
+        NOTE: this is a special purpose function. It is useful when multiple operations that take in
+        PetDataArrayLike are chained. In which case self.return_raw_result = False will have some
+        slight performance benefit, otherwise you'd have to do:
+
+            ```
+            pd1 = PetDataset(arr)
+            res1 = pd1.map_each_var(fn1)
+            pd2 = PetDataset(res1)  # each of this call incurs a overhead.
+            res2 = pd2.map_each_var(fn2)
+            ```
+
+        Instead, setting `with_return_raw_result(False)` we can chain methods:
+
+            ```
+            pet_ds = PetDataset(arr)
+            # no over head since the return type of each method is already a PetDataset
+            result = pet_ds.map_each_var(fn1).map_each_var(fn2)...
+            ```
+
+        Finally we can set:
+
+            ```
+            raw_result =
+                pet_ds.map_each_var(fn1)
+                    .map_each_var(fn2)
+                    ...
+                    .with_return_raw_result()
+                    .map_each_var(final_fn)
+            ```
+
+        if we explicitly need the raw result at the end.
+
+        The default (True) is always to return the original array type. This would be the case for
+        most one-off computations.
         """
         self.return_raw_result = return_raw_result