Clarify usage of sourceModified flag

[DanTup]

I'm trying to improve handling of breakpoints when there are modified files. There's a sourceModified flag but the spec is not very detailed about what it means:

  /**
   * A value of true indicates that the underlying source has been modified
   * which results in new breakpoint locations.
   */

There's a little more info from @weinand at microsoft/vscode#8077 (comment) which says:

If breakpoints are changed and ...

• source is not dirty then a setBreakpoints request with the attribute sourceModified set to false is issued immediately.
• source is dirty, all breakpoint modifications are tracked but no setBreakpoints requests are issued until the next save of the source. In the meantime breakpoints are shown as unverified. After the save a single setBreakpoint request with the attribute sourceModified set to true is issued.

In both cases the result status returned from the setBreakpoints request is applied immediately.

However, this doesn't seem to match what I'm seeing when testing, because sourceModified is false even when my file is modified:

// Add a breakpoint on line 1
[10:52:44] [DAP] [Info] ==> {"command":"setBreakpoints","arguments":{"source":{"name":"main.dart","path":"/.../main.dart"},"lines":[1],"breakpoints":[{"line":1}],"sourceModified":false},"type":"request","seq":8}

// Modify file (append text to a comment on line 1) but do not save

// Add a breakpoint on line 2
[10:52:58] [DAP] [Info] ==> {"command":"setBreakpoints","arguments":{"source":{"name":"main.dart","path":"/.../main.dart"},"lines":[1,2],"breakpoints":[{"line":1},{"line":2}],"sourceModified":false},"type":"request","seq":11}

// Save file

// Add a breakpoint on line 3
[10:53:09] [DAP] [Info] ==> {"command":"setBreakpoints","arguments":{"source":{"name":"main.dart","path":"/.../main.dart"},"lines":[1,2,3],"breakpoints":[{"line":1},{"line":2},{"line":3}],"sourceModified":false},"type":"request","seq":15}

I'm also a little sure about the intended use of sourceModified. What I was hoping would happen is that VS Code would set sourceModified: true any time it sends breakpoints but the source file is dirty (if it chooses to send them). This means a DA could choose to completely ignore setBreakpoint requests when this flag is true to avoid setting breakpoints in invalid locations. However, for this to work, it would also require the client to send a setBreakpoints (with sourceModified: false) after any save, if breakpoints had been modified.

With the current behaviour logged above, sourceModified is never set. I've filed microsoft/vscode#175872 about this, but without the spec being very explicit about how this should work, it's hard to describe exactly what the expected behaviour is (is the flag wrong, or should VS Code not have called setBreakpoints until the file was saved?).

[roblourens]

Replied at microsoft/vscode#175872, we can discuss it there for now