Improve comments a bit

examples/pos/probabilistic.effekt

@@ -60,11 +60,11 @@ def heap[R] { prog: => R / Heap } = {
 
 // effects for expressing some constructs on RVs
 
-/// Cond expresses a RV which depends on a some other RVs listed in
-/// listRef. The list listProbabilities contains the probabilities with which the
+/// Cond expresses a RV which depends on a some other RVs listed in listRef.
+/// The list listProbabilities contains the probabilities with which the
 /// expressed RV is true given that the RVs in listRef are true/false:
-/// if there are n RVs in listRef, then there are supposed to be
-/// 2^n elements in listProbabilities, one for each combination of true/false
+/// if there are n RVs in listRef, then there are supposed to be 2^n
+/// elements in listProbabilities, one for each combination of true/false
 /// for the elements in listRef.
 /// The order in listProbabilities goes from all RVs in listRef are false to
 /// all of them are true in ascending order, when false is read
@@ -76,7 +76,7 @@ def heap[R] { prog: => R / Heap } = {
 effect Cond(listRef: List[Ref], listProbabilities: List[Double]): Ref
 
 /// Conj and Disj express the conjunction and disjunction of
-/// RVs x and y, i.e. Conj(x, y) is true iff x and y are both true,
+/// RVs x and y, i.e., Conj(x, y) is true iff x and y are both true,
 /// where Disj(x, y) is false iff x and y are both false.
 effect Conj(x: Ref, y: Ref): Ref
 effect Disj(x: Ref, y: Ref): Ref
@@ -107,15 +107,15 @@ def pow(base: Int, exp: Int): Int = {
   else { base * pow(base, exp - 1) }
 }
 
-/// observe a RV, failing when the same RV
-/// is observed again with a different result
+/// Observe a RV, failing when the same RV
+/// is observed again with a different result.
 def observe(ref: Ref, b: Bool) =
   do get(ref) match {
     case Unobserved() => do put(ref, Observed(b))
     case Observed(y) => if (b == y) { () } else { do Fail() }
   }
 
-/// observe each (if the Bool list is long enough) RV in a list
+/// Observe each (if the Bool list is long enough) RV in a list.
 def observeList(listRef: List[Ref], listBool: List[Bool]): Unit / { Heap, Fail } = {
   listRef match {
     case Nil() => ()
@@ -130,9 +130,9 @@ def observeList(listRef: List[Ref], listBool: List[Bool]): Unit / { Heap, Fail }
 
 /// Convert a non-negative number to a list of booleans with specified length.
 /// The conversion proceeds according to the interpretation of positions
-/// in a list described above for the Cond effect. If the numberis too large
+/// in a list as described above for the Cond effect. If the number is too large
 /// to fit into the list of the specified length, the higher bits are truncated.
-/// Example: when the length is 3, the correspondence is
+/// Example: given that the length is 3, the correspondence is
 /// decimal number  binary number  bool list
 /// 0               000            [false,false,false]
 /// 1               001            [false,false,true]
@@ -156,7 +156,7 @@ def toBoolList(length: Int, number: Int): List[Bool] = try {
 } with Fail[A] { () => println("toBoolList: Unexpected negative number."); [] }
 
 /// Observe the possibilities of true/false combinations for the RVs
-/// in listRef corresponding to the above described interpretation of
+/// in listRef corresponding to the above-described interpretation of
 /// positions in a list up to position index, and score in each case
 /// with the probability at the corresponding position in listProbabilities.
 /// Usually this function is called with index = (2^n - 1) where n is the
@@ -187,8 +187,8 @@ def fresh(): Ref / Heap = do empty(Unobserved())
 
 /// Handler for effects for probabilistic constructs:
 /// run the program prog forwards collecting all effects for probabilistic
-/// constructs, then observe the result RV in prog to be as expected and then
-/// go backwards through the program enumerating all possible possible ways
+/// constructs, then observe the result RV in prog to be as expected and
+/// then go backwards through the program enumerating all possible ways
 /// how the result could have come about from the input RV.
 def handleLang(expected: Bool) { prog: Ref => Ref / { Cond, Conj, Disj, Prior }}: Var / { IndexOutOfBounds, Score, Fail, Fork } = heap {
   val input = fresh();