User in full control over comments

[pjljvandelaar]

We would like to give the user more control over the comments: Currently, before and after trivia are supported but this can lead to duplication of comments. E.g. with find pattern

$S_A; $S_B;

and replace pattern

$S_B; $S_A;

with before and after equal to All_Trivia.

The find pattern matches the following instance

a; 
-- comment
b;

results in the replacement

-- comment
b; 
a;
-- comment

However, we also want to enable tools to add marks to the code, such that consequent changes are limited to the marked sections. These comments should NOT be accessible by other users.

[pjljvandelaar]

Problem

The following real world example shows why comment handling is needed.

-      return not
-        (R1 (1).X > R2 (2).X           --  R1 on the right of R2
-         or else R2 (1).X > R1 (2).X   --  R2 on the right of R1
-         or else R1 (1).Y > R2 (2).Y   --  R1 below R2
-         or else R2 (1).Y > R1 (2).Y); --  R1 above R2
+      return
+        (((R1 (1).X <= R2 (2).X) and then (R2 (1).X <= R1 (2).X))
+         and then (R1 (1).Y <= R2 (2).Y))
+        and then (R2 (1).Y <= R1 (2).Y); --  R1 above R2

Although one might wonder whether the comment is still correct after the transformation.

A Solution

Comments within place holders are part of that place holder. In find and replace, these comments are thus just copied as part of the place holder. Yet how to handle comments surrounding the place holders? Users typically associate these surrounding comments in a particular way with the place holder, e.g. comments before a function describe that function, comment after a statement describe that statement. We however have observed quite some different heuristics in different code bases.

Example: Suppose, the user wants to swap f and g.

  -- C0
  f;
  -- C1
  g;
  -- C2

What does he wants as end result?

  -- C0
  g;
  -- C1
  f;
  -- C2

  -- C1
  g;
  -- C2
  -- C0
  f;

  g;
  -- C2
  -- C0
  f;
  -- C1

or even

  -- C1
  g;
  -- C2
  -- C0
  f;
  -- C1

Proposed solution:

• Introduce placeholders for comments to specify which are relevant and how they should be manipulated

Questions:

1. Should we match comments (only) or trivia (comments + white spaces)? Proposal: comments only
   2. Should we differentiate between single and multi-line / multiple comments? Proposal: Only support list of comments (enforce usage of $M_ names) Only add that a match can fail due to the absence of comment when there is a real pull!
2. Should we (still) allow our users to add regular comments to a replacement pattern? e.g., z := max (x,y); -- PvdL: 2022-05-02 if statement replaced by max function Proposal: Yes, just like we still allow identifiers as well!

3. Does a user want to specify that he only wants the last part of a comment? What is a comment?

   -- x
   -- y

   Two comment lines: One or two comments?

   -- x
   
   -- y 

   Two comments lines separated by a white line: One or two comments?

So has

-- $M_X 
-- $M_Y 

a clear interpretation?

Ada Examples

Pattern

-- $S_comment_before
function $S_function

will match instance

-- Describing comment of my_function
function my_function

Pattern

-- $M_comment_before
function $S_function

will match instance

-- Describing multiline
-- comment of my_function
function my_function

[pjljvandelaar]

The following design is proposed (for now):

In find patterns

• :heavy_check_mark: Either only comments with placeholders allowed
• Or both comments with and without placeholders allowed: comments without placeholders must be exactly matched.

Note: using a check function, a comment can still be matched to a particular text.

In replace patterns

• Either only comments with placeholders allowed
• :heavy_check_mark: Or both comments with and without placeholders allowed, comments without placeholders are just inserted as is.