Improve the generated comments

1 files changed, 57 insertions, 55 deletions

diff --git a/tests/fstar/misc/NoNestedBorrows.fst b/tests/fstar/misc/NoNestedBorrows.fst
index 3770ab5d..d790bfa9 100644
--- a/tests/fstar/misc/NoNestedBorrows.fst
+++ b/tests/fstar/misc/NoNestedBorrows.fst
@@ -30,46 +30,46 @@ type sum_t (t1 t2 : Type0) =
 | SumLeft : t1 -> sum_t t1 t2
 | SumRight : t2 -> sum_t t1 t2
 
-(** [no_nested_borrows::neg_test] *)
+(** [no_nested_borrows::neg_test]: forward function *)
 let neg_test_fwd (x : i32) : result i32 =
   i32_neg x
 
-(** [no_nested_borrows::add_test] *)
+(** [no_nested_borrows::add_test]: forward function *)
 let add_test_fwd (x : u32) (y : u32) : result u32 =
   u32_add x y
 
-(** [no_nested_borrows::subs_test] *)
+(** [no_nested_borrows::subs_test]: forward function *)
 let subs_test_fwd (x : u32) (y : u32) : result u32 =
   u32_sub x y
 
-(** [no_nested_borrows::div_test] *)
+(** [no_nested_borrows::div_test]: forward function *)
 let div_test_fwd (x : u32) (y : u32) : result u32 =
   u32_div x y
 
-(** [no_nested_borrows::div_test1] *)
+(** [no_nested_borrows::div_test1]: forward function *)
 let div_test1_fwd (x : u32) : result u32 =
   u32_div x 2
 
-(** [no_nested_borrows::rem_test] *)
+(** [no_nested_borrows::rem_test]: forward function *)
 let rem_test_fwd (x : u32) (y : u32) : result u32 =
   u32_rem x y
 
-(** [no_nested_borrows::cast_test] *)
+(** [no_nested_borrows::cast_test]: forward function *)
 let cast_test_fwd (x : u32) : result i32 =
   scalar_cast U32 I32 x
 
-(** [no_nested_borrows::test2] *)
+(** [no_nested_borrows::test2]: forward function *)
 let test2_fwd : result unit =
   let* _ = u32_add 23 44 in Return ()
 
 (** Unit test for [no_nested_borrows::test2] *)
 let _ = assert_norm (test2_fwd = Return ())
 
-(** [no_nested_borrows::get_max] *)
+(** [no_nested_borrows::get_max]: forward function *)
 let get_max_fwd (x : u32) (y : u32) : result u32 =
   if x >= y then Return x else Return y
 
-(** [no_nested_borrows::test3] *)
+(** [no_nested_borrows::test3]: forward function *)
 let test3_fwd : result unit =
   let* x = get_max_fwd 4 3 in
   let* y = get_max_fwd 10 11 in
@@ -79,21 +79,21 @@ let test3_fwd : result unit =
 (** Unit test for [no_nested_borrows::test3] *)
 let _ = assert_norm (test3_fwd = Return ())
 
-(** [no_nested_borrows::test_neg1] *)
+(** [no_nested_borrows::test_neg1]: forward function *)
 let test_neg1_fwd : result unit =
   let* y = i32_neg 3 in if not (y = -3) then Fail Failure else Return ()
 
 (** Unit test for [no_nested_borrows::test_neg1] *)
 let _ = assert_norm (test_neg1_fwd = Return ())
 
-(** [no_nested_borrows::refs_test1] *)
+(** [no_nested_borrows::refs_test1]: forward function *)
 let refs_test1_fwd : result unit =
   if not (1 = 1) then Fail Failure else Return ()
 
 (** Unit test for [no_nested_borrows::refs_test1] *)
 let _ = assert_norm (refs_test1_fwd = Return ())
 
-(** [no_nested_borrows::refs_test2] *)
+(** [no_nested_borrows::refs_test2]: forward function *)
 let refs_test2_fwd : result unit =
   if not (2 = 2)
   then Fail Failure
@@ -108,47 +108,47 @@ let refs_test2_fwd : result unit =
 (** Unit test for [no_nested_borrows::refs_test2] *)
 let _ = assert_norm (refs_test2_fwd = Return ())
 
-(** [no_nested_borrows::test_list1] *)
+(** [no_nested_borrows::test_list1]: forward function *)
 let test_list1_fwd : result unit =
   Return ()
 
 (** Unit test for [no_nested_borrows::test_list1] *)
 let _ = assert_norm (test_list1_fwd = Return ())
 
-(** [no_nested_borrows::test_box1] *)
+(** [no_nested_borrows::test_box1]: forward function *)
 let test_box1_fwd : result unit =
   let b = 1 in let x = b in if not (x = 1) then Fail Failure else Return ()
 
 (** Unit test for [no_nested_borrows::test_box1] *)
 let _ = assert_norm (test_box1_fwd = Return ())
 
-(** [no_nested_borrows::copy_int] *)
+(** [no_nested_borrows::copy_int]: forward function *)
 let copy_int_fwd (x : i32) : result i32 =
   Return x
 
-(** [no_nested_borrows::test_unreachable] *)
+(** [no_nested_borrows::test_unreachable]: forward function *)
 let test_unreachable_fwd (b : bool) : result unit =
   if b then Fail Failure else Return ()
 
-(** [no_nested_borrows::test_panic] *)
+(** [no_nested_borrows::test_panic]: forward function *)
 let test_panic_fwd (b : bool) : result unit =
   if b then Fail Failure else Return ()
 
-(** [no_nested_borrows::test_copy_int] *)
+(** [no_nested_borrows::test_copy_int]: forward function *)
 let test_copy_int_fwd : result unit =
   let* y = copy_int_fwd 0 in if not (0 = y) then Fail Failure else Return ()
 
 (** Unit test for [no_nested_borrows::test_copy_int] *)
 let _ = assert_norm (test_copy_int_fwd = Return ())
 
-(** [no_nested_borrows::is_cons] *)
+(** [no_nested_borrows::is_cons]: forward function *)
 let is_cons_fwd (t : Type0) (l : list_t t) : result bool =
   begin match l with
   | ListCons x l0 -> Return true
   | ListNil -> Return false
   end
 
-(** [no_nested_borrows::test_is_cons] *)
+(** [no_nested_borrows::test_is_cons]: forward function *)
 let test_is_cons_fwd : result unit =
   let l = ListNil in
   let* b = is_cons_fwd i32 (ListCons 0 l) in
@@ -157,14 +157,14 @@ let test_is_cons_fwd : result unit =
 (** Unit test for [no_nested_borrows::test_is_cons] *)
 let _ = assert_norm (test_is_cons_fwd = Return ())
 
-(** [no_nested_borrows::split_list] *)
+(** [no_nested_borrows::split_list]: forward function *)
 let split_list_fwd (t : Type0) (l : list_t t) : result (t & (list_t t)) =
   begin match l with
   | ListCons hd tl -> Return (hd, tl)
   | ListNil -> Fail Failure
   end
 
-(** [no_nested_borrows::test_split_list] *)
+(** [no_nested_borrows::test_split_list]: forward function *)
 let test_split_list_fwd : result unit =
   let l = ListNil in
   let* p = split_list_fwd i32 (ListCons 0 l) in
@@ -174,16 +174,16 @@ let test_split_list_fwd : result unit =
 (** Unit test for [no_nested_borrows::test_split_list] *)
 let _ = assert_norm (test_split_list_fwd = Return ())
 
-(** [no_nested_borrows::choose] *)
+(** [no_nested_borrows::choose]: forward function *)
 let choose_fwd (t : Type0) (b : bool) (x : t) (y : t) : result t =
   if b then Return x else Return y
 
-(** [no_nested_borrows::choose] *)
+(** [no_nested_borrows::choose]: backward function 0 *)
 let choose_back
   (t : Type0) (b : bool) (x : t) (y : t) (ret : t) : result (t & t) =
   if b then Return (ret, y) else Return (x, ret)
 
-(** [no_nested_borrows::choose_test] *)
+(** [no_nested_borrows::choose_test]: forward function *)
 let choose_test_fwd : result unit =
   let* z = choose_fwd i32 true 0 0 in
   let* z0 = i32_add z 1 in
@@ -198,7 +198,7 @@ let choose_test_fwd : result unit =
 (** Unit test for [no_nested_borrows::choose_test] *)
 let _ = assert_norm (choose_test_fwd = Return ())
 
-(** [no_nested_borrows::test_char] *)
+(** [no_nested_borrows::test_char]: forward function *)
 let test_char_fwd : result char =
   Return 'a'
 
@@ -212,14 +212,14 @@ and tree_t (t : Type0) =
 | TreeLeaf : t -> tree_t t
 | TreeNode : t -> node_elem_t t -> tree_t t -> tree_t t
 
-(** [no_nested_borrows::list_length] *)
+(** [no_nested_borrows::list_length]: forward function *)
 let rec list_length_fwd (t : Type0) (l : list_t t) : result u32 =
   begin match l with
   | ListCons x l1 -> let* i = list_length_fwd t l1 in u32_add 1 i
   | ListNil -> Return 0
   end
 
-(** [no_nested_borrows::list_nth_shared] *)
+(** [no_nested_borrows::list_nth_shared]: forward function *)
 let rec list_nth_shared_fwd (t : Type0) (l : list_t t) (i : u32) : result t =
   begin match l with
   | ListCons x tl ->
@@ -229,7 +229,7 @@ let rec list_nth_shared_fwd (t : Type0) (l : list_t t) (i : u32) : result t =
   | ListNil -> Fail Failure
   end
 
-(** [no_nested_borrows::list_nth_mut] *)
+(** [no_nested_borrows::list_nth_mut]: forward function *)
 let rec list_nth_mut_fwd (t : Type0) (l : list_t t) (i : u32) : result t =
   begin match l with
   | ListCons x tl ->
@@ -239,7 +239,7 @@ let rec list_nth_mut_fwd (t : Type0) (l : list_t t) (i : u32) : result t =
   | ListNil -> Fail Failure
   end
 
-(** [no_nested_borrows::list_nth_mut] *)
+(** [no_nested_borrows::list_nth_mut]: backward function 0 *)
 let rec list_nth_mut_back
   (t : Type0) (l : list_t t) (i : u32) (ret : t) : result (list_t t) =
   begin match l with
@@ -253,7 +253,7 @@ let rec list_nth_mut_back
   | ListNil -> Fail Failure
   end
 
-(** [no_nested_borrows::list_rev_aux] *)
+(** [no_nested_borrows::list_rev_aux]: forward function *)
 let rec list_rev_aux_fwd
   (t : Type0) (li : list_t t) (lo : list_t t) : result (list_t t) =
   begin match li with
@@ -261,12 +261,13 @@ let rec list_rev_aux_fwd
   | ListNil -> Return lo
   end
 
-(** [no_nested_borrows::list_rev] *)
+(** [no_nested_borrows::list_rev]: merged forward/backward function
+    (there is a single backward function, and the forward function returns ()) *)
 let list_rev_fwd_back (t : Type0) (l : list_t t) : result (list_t t) =
   let li = mem_replace_fwd (list_t t) l ListNil in
   list_rev_aux_fwd t li ListNil
 
-(** [no_nested_borrows::test_list_functions] *)
+(** [no_nested_borrows::test_list_functions]: forward function *)
 let test_list_functions_fwd : result unit =
   let l = ListNil in
   let l0 = ListCons 2 l in
@@ -302,48 +303,48 @@ let test_list_functions_fwd : result unit =
 (** Unit test for [no_nested_borrows::test_list_functions] *)
 let _ = assert_norm (test_list_functions_fwd = Return ())
 
-(** [no_nested_borrows::id_mut_pair1] *)
+(** [no_nested_borrows::id_mut_pair1]: forward function *)
 let id_mut_pair1_fwd (t1 t2 : Type0) (x : t1) (y : t2) : result (t1 & t2) =
   Return (x, y)
 
-(** [no_nested_borrows::id_mut_pair1] *)
+(** [no_nested_borrows::id_mut_pair1]: backward function 0 *)
 let id_mut_pair1_back
   (t1 t2 : Type0) (x : t1) (y : t2) (ret : (t1 & t2)) : result (t1 & t2) =
   let (x0, x1) = ret in Return (x0, x1)
 
-(** [no_nested_borrows::id_mut_pair2] *)
+(** [no_nested_borrows::id_mut_pair2]: forward function *)
 let id_mut_pair2_fwd (t1 t2 : Type0) (p : (t1 & t2)) : result (t1 & t2) =
   let (x, x0) = p in Return (x, x0)
 
-(** [no_nested_borrows::id_mut_pair2] *)
+(** [no_nested_borrows::id_mut_pair2]: backward function 0 *)
 let id_mut_pair2_back
   (t1 t2 : Type0) (p : (t1 & t2)) (ret : (t1 & t2)) : result (t1 & t2) =
   let (x, x0) = ret in Return (x, x0)
 
-(** [no_nested_borrows::id_mut_pair3] *)
+(** [no_nested_borrows::id_mut_pair3]: forward function *)
 let id_mut_pair3_fwd (t1 t2 : Type0) (x : t1) (y : t2) : result (t1 & t2) =
   Return (x, y)
 
-(** [no_nested_borrows::id_mut_pair3] *)
+(** [no_nested_borrows::id_mut_pair3]: backward function 0 *)
 let id_mut_pair3_back'a
   (t1 t2 : Type0) (x : t1) (y : t2) (ret : t1) : result t1 =
   Return ret
 
-(** [no_nested_borrows::id_mut_pair3] *)
+(** [no_nested_borrows::id_mut_pair3]: backward function 1 *)
 let id_mut_pair3_back'b
   (t1 t2 : Type0) (x : t1) (y : t2) (ret : t2) : result t2 =
   Return ret
 
-(** [no_nested_borrows::id_mut_pair4] *)
+(** [no_nested_borrows::id_mut_pair4]: forward function *)
 let id_mut_pair4_fwd (t1 t2 : Type0) (p : (t1 & t2)) : result (t1 & t2) =
   let (x, x0) = p in Return (x, x0)
 
-(** [no_nested_borrows::id_mut_pair4] *)
+(** [no_nested_borrows::id_mut_pair4]: backward function 0 *)
 let id_mut_pair4_back'a
   (t1 t2 : Type0) (p : (t1 & t2)) (ret : t1) : result t1 =
   Return ret
 
-(** [no_nested_borrows::id_mut_pair4] *)
+(** [no_nested_borrows::id_mut_pair4]: backward function 1 *)
 let id_mut_pair4_back'b
   (t1 t2 : Type0) (p : (t1 & t2)) (ret : t2) : result t2 =
   Return ret
@@ -351,15 +352,15 @@ let id_mut_pair4_back'b
 (** [no_nested_borrows::StructWithTuple] *)
 type struct_with_tuple_t (t1 t2 : Type0) = { struct_with_tuple_p : (t1 & t2); }
 
-(** [no_nested_borrows::new_tuple1] *)
+(** [no_nested_borrows::new_tuple1]: forward function *)
 let new_tuple1_fwd : result (struct_with_tuple_t u32 u32) =
   Return { struct_with_tuple_p = (1, 2) }
 
-(** [no_nested_borrows::new_tuple2] *)
+(** [no_nested_borrows::new_tuple2]: forward function *)
 let new_tuple2_fwd : result (struct_with_tuple_t i16 i16) =
   Return { struct_with_tuple_p = (1, 2) }
 
-(** [no_nested_borrows::new_tuple3] *)
+(** [no_nested_borrows::new_tuple3]: forward function *)
 let new_tuple3_fwd : result (struct_with_tuple_t u64 i64) =
   Return { struct_with_tuple_p = (1, 2) }
 
@@ -369,11 +370,11 @@ type struct_with_pair_t (t1 t2 : Type0) =
   struct_with_pair_p : pair_t t1 t2;
 }
 
-(** [no_nested_borrows::new_pair1] *)
+(** [no_nested_borrows::new_pair1]: forward function *)
 let new_pair1_fwd : result (struct_with_pair_t u32 u32) =
   Return { struct_with_pair_p = { pair_x = 1; pair_y = 2 } }
 
-(** [no_nested_borrows::test_constants] *)
+(** [no_nested_borrows::test_constants]: forward function *)
 let test_constants_fwd : result unit =
   let* swt = new_tuple1_fwd in
   let (i, _) = swt.struct_with_tuple_p in
@@ -398,31 +399,32 @@ let test_constants_fwd : result unit =
 (** Unit test for [no_nested_borrows::test_constants] *)
 let _ = assert_norm (test_constants_fwd = Return ())
 
-(** [no_nested_borrows::test_weird_borrows1] *)
+(** [no_nested_borrows::test_weird_borrows1]: forward function *)
 let test_weird_borrows1_fwd : result unit =
   Return ()
 
 (** Unit test for [no_nested_borrows::test_weird_borrows1] *)
 let _ = assert_norm (test_weird_borrows1_fwd = Return ())
 
-(** [no_nested_borrows::test_mem_replace] *)
+(** [no_nested_borrows::test_mem_replace]: merged forward/backward function
+    (there is a single backward function, and the forward function returns ()) *)
 let test_mem_replace_fwd_back (px : u32) : result u32 =
   let y = mem_replace_fwd u32 px 1 in
   if not (y = 0) then Fail Failure else Return 2
 
-(** [no_nested_borrows::test_shared_borrow_bool1] *)
+(** [no_nested_borrows::test_shared_borrow_bool1]: forward function *)
 let test_shared_borrow_bool1_fwd (b : bool) : result u32 =
   if b then Return 0 else Return 1
 
-(** [no_nested_borrows::test_shared_borrow_bool2] *)
+(** [no_nested_borrows::test_shared_borrow_bool2]: forward function *)
 let test_shared_borrow_bool2_fwd : result u32 =
   Return 0
 
-(** [no_nested_borrows::test_shared_borrow_enum1] *)
+(** [no_nested_borrows::test_shared_borrow_enum1]: forward function *)
 let test_shared_borrow_enum1_fwd (l : list_t u32) : result u32 =
   begin match l with | ListCons i l0 -> Return 1 | ListNil -> Return 0 end
 
-(** [no_nested_borrows::test_shared_borrow_enum2] *)
+(** [no_nested_borrows::test_shared_borrow_enum2]: forward function *)
 let test_shared_borrow_enum2_fwd : result u32 =
   Return 0