Skip to content

Commit 2cf5866

Browse files
cknittclaude
andcommitted
Place five kinds of comments where they were written when formatting
Why: Five cases from #9107 put comments or doc comments in a different place, and one of them changed the attribute order in the AST. A single hugged parameter with a doc comment, or a callback parameter with one, was printed with its pattern at column 0. A comment after the `)` of a `switch`, `if`, `while`, loop or `try` operand was not adjacent to the operand, so it went into the block. The tail spread of a list printed its leading comments after the dots. Doc comments after an attribute were moved in front of all attributes. A file with only a line comment got an extra newline. A comment now records whether a `)` precedes it, and the operand of a block construct also keeps the comments after its closing parentheses that come before the block. A doc comment stays in front of the attributes only when it already was, so later ones print in their place. Format modified (doc comment on a hugged parameter): Example: let f = (/** r */ {x, y}) => x Before (rescript): let f = (/** r */ {x, y}) => x After (rescript): let f = ( /** r */ {x, y}, ) => x Format modified (comment after a parenthesized operand): Example: let v = switch (x) // c1 { | 1 => 2 | _ => 3 } Before (rescript): let v = switch x { // c1 | 1 => 2 | _ => 3 } After (rescript): let v = switch ( x // c1 ) { | 1 => 2 | _ => 3 } Format modified (comment before a list's tail spread): Example: let l = list{1, /* c */ ...xs} Before (rescript): let l = list{1, .../* c */ xs} After (rescript): let l = list{1, /* c */ ...xs} AST modified (doc comment after an attribute, after formatting): Example: type u = /** d1 */ @A /** d2 */ {x: int} Before (parse): type_declaration "u" attribute "res.doc" attribute "res.doc" attribute "a" After (parse): type_declaration "u" attribute "res.doc" attribute "a" attribute "res.doc" Format modified (file with only a line comment): Example: // c Before (text): "// c\n\n" After (text): "// c\n" Review: Can a `)` inside the block be taken for the operand's? No: only comments that end before the first case, the `then` branch or the body, attributes included, are considered. Fixes: #9107 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kbf3gGkPma9LAZimuQjnrP Signed-off-by: Christoph Knittel <ck@cca.io>
1 parent 85f31fb commit 2cf5866

24 files changed

Lines changed: 447 additions & 83 deletions
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- Fix the formatter's placement of doc comments on hugged or callback parameters and after attributes, of comments after a parenthesized `switch`/`if`/loop operand or before a list's tail spread, and the extra newline after a file with only a line comment.

‎compiler/syntax/src/res_comment.ml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ type t = {
1313
loc: Location.t;
1414
mutable prev_tok_end_pos: Lexing.position;
1515
mutable prev_tok_is_question: bool;
16+
mutable prev_tok_is_rparen: bool;
1617
(* Checkpoints restore comment lists, not this field. A speculative JSX parse
1718
must reproduce this marking on reparse; otherwise defer it until commit or
1819
restore it on rollback. *)
@@ -31,6 +32,10 @@ let prev_tok_is_question t = t.prev_tok_is_question
3132

3233
let set_prev_tok_is_question t b = t.prev_tok_is_question <- b
3334

35+
let prev_tok_is_rparen t = t.prev_tok_is_rparen
36+
37+
let set_prev_tok_is_rparen t b = t.prev_tok_is_rparen <- b
38+
3439
let is_single_line_comment t = t.style = SingleLine
3540

3641
let to_block_if_safe t =
@@ -63,6 +68,7 @@ let make_single_line_comment ~loc txt =
6368
style = SingleLine;
6469
prev_tok_end_pos = Lexing.dummy_pos;
6570
prev_tok_is_question = false;
71+
prev_tok_is_rparen = false;
6672
jsx_container = None;
6773
}
6874

@@ -75,6 +81,7 @@ let make_multi_line_comment ~loc ~doc_comment ~standalone txt =
7581
else MultiLine);
7682
prev_tok_end_pos = Lexing.dummy_pos;
7783
prev_tok_is_question = false;
84+
prev_tok_is_rparen = false;
7885
jsx_container = None;
7986
}
8087

‎compiler/syntax/src/res_comment.mli‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ val prev_tok_is_question : t -> bool
1919

2020
val set_prev_tok_is_question : t -> bool -> unit
2121

22+
(* Whether the token before the comment is [)], e.g. the end of a
23+
parenthesized [switch] operand. *)
24+
val prev_tok_is_rparen : t -> bool
25+
26+
val set_prev_tok_is_rparen : t -> bool -> unit
27+
2228
val is_doc_comment : t -> bool
2329

2430
val is_module_comment : t -> bool

‎compiler/syntax/src/res_comments_table.ml‎

Lines changed: 72 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,45 @@ let partition_adjacent_trailing_through_question loc1 comments =
222222
(after_loc1 @ after_question, rest)
223223
| _ -> (after_loc1, rest)
224224

225+
(* Like [partition_adjacent_trailing], and also keeps the comments after the
226+
* closing parentheses around [loc1] that end before [next_pos], as after the
227+
* parenthesized operand of a [switch]:
228+
* switch (x) // comment
229+
* { ... }
230+
* The comment trails [x]. The parentheses are not part of [loc1], and a [)]
231+
* after [next_pos] belongs to the code that follows. *)
232+
let partition_adjacent_trailing_through_rparens loc1 ~next_pos comments =
233+
let rec loop (loc1 : Location.t) after_loc1 comments =
234+
let adjacent, rest = partition_adjacent_trailing loc1 comments in
235+
let after_loc1 = List.rev_append adjacent after_loc1 in
236+
match rest with
237+
| first :: _
238+
when Comment.prev_tok_is_rparen first
239+
&& (Comment.prev_tok_end_pos first).pos_cnum > loc1.loc_end.pos_cnum
240+
&& (Comment.loc first).loc_end.pos_cnum <= next_pos.Lexing.pos_cnum
241+
->
242+
loop {loc1 with loc_end = Comment.prev_tok_end_pos first} after_loc1 rest
243+
| _ -> (List.rev after_loc1, rest)
244+
in
245+
loop loc1 [] comments
246+
247+
(* Where a node with [loc] and [attrs] starts, its attributes included *)
248+
let start_pos_with_attributes (loc : Location.t) (attrs : Parsetree.attributes)
249+
=
250+
List.fold_left
251+
(fun (pos : Lexing.position) (({loc}, _) : Parsetree.attribute) ->
252+
if loc.loc_start.pos_cnum < pos.pos_cnum then loc.loc_start else pos)
253+
loc.loc_start attrs
254+
255+
let expr_start_pos (expr : Parsetree.expression) =
256+
start_pos_with_attributes expr.pexp_loc expr.pexp_attributes
257+
258+
let case_start_pos (case : Parsetree.case) =
259+
match case.pc_bar with
260+
| Some pos -> pos
261+
| None ->
262+
start_pos_with_attributes case.pc_lhs.ppat_loc case.pc_lhs.ppat_attributes
263+
225264
(* Splits comments that follow a location but come before another token.
226265
* This is particularly useful for handling comments between two tokens
227266
* where traditional leading/trailing partitioning isn't precise enough.
@@ -1014,7 +1053,8 @@ and walk_value_binding vb t comments =
10141053

10151054
(* Walks the scrutinee of a switch or the body of a try, and returns the
10161055
comments after it. *)
1017-
and walk_switch_or_try_head (expr : Parsetree.expression) t comments =
1056+
(* [next_pos] is where the cases or the [finally] block start *)
1057+
and walk_switch_or_try_head (expr : Parsetree.expression) ~next_pos t comments =
10181058
let before, inside, after = partition_by_loc comments expr.pexp_loc in
10191059
let after =
10201060
if is_block_expr expr then (
@@ -1026,7 +1066,9 @@ and walk_switch_or_try_head (expr : Parsetree.expression) t comments =
10261066
walk_expression expr t inside;
10271067
after)
10281068
in
1029-
let after_expr, rest = partition_adjacent_trailing expr.pexp_loc after in
1069+
let after_expr, rest =
1070+
partition_adjacent_trailing_through_rparens expr.pexp_loc ~next_pos after
1071+
in
10301072
attach t.trailing expr.pexp_loc after_expr;
10311073
rest
10321074

@@ -1337,18 +1379,21 @@ and walk_expression expr t comments =
13371379
let leading, rest = partition_leading_trailing comments expr.pexp_loc in
13381380
attach t.leading expr.pexp_loc leading;
13391381
let leading, inside, trailing = partition_by_loc rest if_expr.pexp_loc in
1382+
let next_pos = expr_start_pos then_expr in
13401383
let comments =
13411384
if is_block_expr if_expr then (
13421385
let after_expr, comments =
1343-
partition_adjacent_trailing if_expr.pexp_loc trailing
1386+
partition_adjacent_trailing_through_rparens if_expr.pexp_loc ~next_pos
1387+
trailing
13441388
in
13451389
walk_expression if_expr t (List.concat [leading; inside; after_expr]);
13461390
comments)
13471391
else (
13481392
attach t.leading if_expr.pexp_loc leading;
13491393
walk_expression if_expr t inside;
13501394
let after_expr, comments =
1351-
partition_adjacent_trailing if_expr.pexp_loc trailing
1395+
partition_adjacent_trailing_through_rparens if_expr.pexp_loc ~next_pos
1396+
trailing
13521397
in
13531398
attach t.trailing if_expr.pexp_loc after_expr;
13541399
comments)
@@ -1386,18 +1431,21 @@ and walk_expression expr t comments =
13861431
attach t.trailing expr.pexp_loc trailing)
13871432
| Pexp_while (expr1, expr2) ->
13881433
let leading, inside, trailing = partition_by_loc comments expr1.pexp_loc in
1434+
let next_pos = expr_start_pos expr2 in
13891435
let rest =
13901436
if is_block_expr expr1 then (
13911437
let after_expr, rest =
1392-
partition_adjacent_trailing expr1.pexp_loc trailing
1438+
partition_adjacent_trailing_through_rparens expr1.pexp_loc ~next_pos
1439+
trailing
13931440
in
13941441
walk_expression expr1 t (List.concat [leading; inside; after_expr]);
13951442
rest)
13961443
else (
13971444
attach t.leading expr1.pexp_loc leading;
13981445
walk_expression expr1 t inside;
13991446
let after_expr, rest =
1400-
partition_adjacent_trailing expr1.pexp_loc trailing
1447+
partition_adjacent_trailing_through_rparens expr1.pexp_loc ~next_pos
1448+
trailing
14011449
in
14021450
attach t.trailing expr1.pexp_loc after_expr;
14031451
rest)
@@ -1418,14 +1466,16 @@ and walk_expression expr t comments =
14181466
attach t.leading expr1.pexp_loc leading;
14191467
walk_expression expr1 t inside;
14201468
let after_expr, rest =
1421-
partition_adjacent_trailing expr1.pexp_loc trailing
1469+
partition_adjacent_trailing_through_rparens expr1.pexp_loc
1470+
~next_pos:(expr_start_pos expr2) trailing
14221471
in
14231472
attach t.trailing expr1.pexp_loc after_expr;
14241473
let leading, inside, trailing = partition_by_loc rest expr2.pexp_loc in
14251474
attach t.leading expr2.pexp_loc leading;
14261475
walk_expression expr2 t inside;
14271476
let after_expr, rest =
1428-
partition_adjacent_trailing expr2.pexp_loc trailing
1477+
partition_adjacent_trailing_through_rparens expr2.pexp_loc
1478+
~next_pos:(expr_start_pos expr3) trailing
14291479
in
14301480
attach t.trailing expr2.pexp_loc after_expr;
14311481
if is_block_expr expr3 then walk_expression expr3 t rest
@@ -1440,13 +1490,23 @@ and walk_expression expr t comments =
14401490
walk_module_expr mod_expr t inside;
14411491
attach t.trailing mod_expr.pmod_loc after
14421492
| Pexp_match (expr, cases) | Pexp_try (expr, cases, None) ->
1443-
let rest = walk_switch_or_try_head expr t comments in
1493+
let next_pos =
1494+
match cases with
1495+
| case :: _ -> case_start_pos case
1496+
| [] -> expr.pexp_loc.loc_end
1497+
in
1498+
let rest = walk_switch_or_try_head expr ~next_pos t comments in
14441499
walk_list (cases |> List.map (fun case -> Case case)) t rest
14451500
| Pexp_try (expr, cases, Some finally) ->
14461501
let before_finally, inside, after =
14471502
partition_by_loc comments finally.pexp_loc
14481503
in
1449-
let rest = walk_switch_or_try_head expr t before_finally in
1504+
let next_pos =
1505+
match cases with
1506+
| case :: _ -> case_start_pos case
1507+
| [] -> expr_start_pos finally
1508+
in
1509+
let rest = walk_switch_or_try_head expr ~next_pos t before_finally in
14501510
(* The finally location starts at its first expression, so comments
14511511
between the cases and that expression lead the finally block. *)
14521512
let rest =
@@ -1763,7 +1823,8 @@ and walk_expression expr t comments =
17631823
attach t.leading expr1.pexp_loc leading;
17641824
walk_expression expr1 t inside;
17651825
let after_expr, rest =
1766-
partition_adjacent_trailing expr1.pexp_loc trailing
1826+
partition_adjacent_trailing_through_rparens expr1.pexp_loc
1827+
~next_pos:(expr_start_pos expr2) trailing
17671828
in
17681829
attach t.trailing expr1.pexp_loc after_expr;
17691830
if is_block_expr expr2 then walk_expression expr2 t rest

‎compiler/syntax/src/res_parser.ml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,10 @@ let rec read cache =
7474
(match preceding_token with
7575
| Token.Question -> true
7676
| _ -> false);
77+
Comment.set_prev_tok_is_rparen c
78+
(match preceding_token with
79+
| Token.Rparen -> true
80+
| _ -> false);
7781
cache.comments <- c :: cache.comments;
7882
cache.scanned <- scanned;
7983
read cache

‎compiler/syntax/src/res_parsetree_viewer.ml‎

Lines changed: 26 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -366,13 +366,6 @@ let collect_ternary_parts expr =
366366
in
367367
collect [] expr
368368

369-
let parameters_should_hug parameters =
370-
match parameters with
371-
| [Parameter {attrs = []; lbl = Nolabel; default_expr = None; pat}]
372-
when is_huggable_pattern pat ->
373-
true
374-
| _ -> false
375-
376369
let should_indent_binary_expr expr =
377370
let same_precedence_sub_expression operator sub_expression =
378371
match sub_expression with
@@ -430,8 +423,33 @@ let is_doc_comment_attribute ((id, payload) : Parsetree.attribute) =
430423
true
431424
| _ -> false
432425

426+
(* Only the doc comments before every other attribute: one after an attribute
427+
stays in its place, so that printing keeps the order of the attributes. *)
433428
let partition_doc_comment_attributes attrs =
434-
List.partition is_doc_comment_attribute attrs
429+
let rec split doc_comments = function
430+
| attr :: attrs when is_doc_comment_attribute attr ->
431+
split (attr :: doc_comments) attrs
432+
| attrs -> (List.rev doc_comments, attrs)
433+
in
434+
split [] attrs
435+
436+
let starts_with_doc_comment = function
437+
| attr :: _ -> is_doc_comment_attribute attr
438+
| [] -> false
439+
440+
let parameter_has_doc_comment = function
441+
| Parameter {attrs; pat} ->
442+
starts_with_doc_comment attrs || starts_with_doc_comment pat.ppat_attributes
443+
| NewTypes {attrs} -> starts_with_doc_comment attrs
444+
445+
(* A leading doc comment is printed on its own line, which a hugged parameter
446+
cannot start. *)
447+
let parameters_should_hug parameters =
448+
match parameters with
449+
| [(Parameter {attrs = []; lbl = Nolabel; default_expr = None; pat} as param)]
450+
when is_huggable_pattern pat && not (parameter_has_doc_comment param) ->
451+
true
452+
| _ -> false
435453

436454
let rec is_fun_expr expr =
437455
match expr.pexp_desc with

‎compiler/syntax/src/res_parsetree_viewer.mli‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,15 +74,26 @@ val collect_ternary_parts :
7474
Parsetree.expression ->
7575
(Parsetree.expression * Parsetree.expression) list * Parsetree.expression
7676

77+
(* Whether the parameter or its pattern starts with a doc comment, which is
78+
printed on its own line *)
79+
val parameter_has_doc_comment : fun_param_kind -> bool
80+
7781
val parameters_should_hug : fun_param_kind list -> bool
7882

7983
val should_indent_binary_expr : Parsetree.expression -> bool
8084
val should_inline_rhs_binary_expr : Parsetree.expression -> bool
8185
val mod_expr_has_attributes : Parsetree.module_expr -> bool
8286
val is_doc_comment_attribute : Parsetree.attribute -> bool
87+
88+
(* The doc comments before every other attribute, and the attributes after
89+
them, which may include later doc comments *)
8390
val partition_doc_comment_attributes :
8491
Parsetree.attributes -> Parsetree.attributes * Parsetree.attributes
8592

93+
(* Whether the first attribute is a doc comment, which is printed on its own
94+
line *)
95+
val starts_with_doc_comment : Parsetree.attributes -> bool
96+
8697
val requires_special_callback_printing_last_arg :
8798
(Asttypes.arg_label * Parsetree.expression) list -> bool
8899
val requires_special_callback_printing_first_arg :

0 commit comments

Comments
 (0)