adding draft of detailed spec

[jmarolf]

@akhera99 and @mikadumont here is a draft of the formal spec. Please call out sections that aren't clear :)

releated to #56541

[mikadumont]

We should make sure this is consistent with IntelliCode Inline Completion. At least validate that theirs also requires at least 2 undo stacks.

[jmarolf]

I will leave that to you @mikadumont

[mikadumont]

We should make sure generate and add are also captured in this list

[jmarolf]

I am not married to this wording. My only argument in its favor is that is is similar to the docs descriptions here.

[mikadumont]

Are we sure we dont want to handle snippets that handles surround with behavior? This needs an update as well.

[jmarolf]

"Surround With" could be its own spec so I left it out for now :)

I think we have enough work here already that we should re-visit "Surround With" separate from this.

We can still discuss it though to make sure we are on the right page. My assumption is that we would not mess with the VS platforms surround with but instead offer a post-statement option.

So if the user types this if at the end of a statement (after a ; essentially)

FileStream stream = File.OpenRead(@"C:\Users\Public\TestFolder\WriteText.txt");
StreamReader streamReader = new(stream);
string text = streamReader.ReadToEnd();[|if|] // Offered 'surround with if block'

They are offered to surround the current line with one of the block snippets.

FileStream stream = File.OpenRead(@"C:\Users\Public\TestFolder\WriteText.txt");
StreamReader streamReader = new(stream);
if (true) // User is put in a special UI mode (!?) where they can choose to expand the selection
{
    string text = streamReader.ReadToEnd();
}

We would then need to offer some custom UI in the editor to allow the user to select what statements should be included in the block.

We may also want a short/dedicated snippet for placing everything in the current block in the new block so if the developer types this:

void M()
{
    FileStream stream = File.OpenRead(@"C:\Users\Public\TestFolder\WriteText.txt");
    StreamReader streamReader = new(stream);
    string text = streamReader.ReadToEnd();|try|] // Offered 'surround with try/catch statement'
                                                  // and     'surround all with try/catch statement'
}

If the developer chooses 'surround all with try/catch statement' then they get:

void M()
{
    try
    {
        FileStream stream = File.OpenRead(@"C:\Users\Public\TestFolder\WriteText.txt");
        StreamReader streamReader = new(stream);
        string text = streamReader.ReadToEnd();
    }
    catch (Exception)
    {
        throw;
    }
}

Unanswered questions with this design:

1. How does the user dynamically expand the set of things they want to include in the block?
2. Should these only be offered at the end of semicolons (;) or are there expression contexts where these should offered?

[jmarolf]

@CyrusNajmabadi I believe you missed the design meeting where we discussed this but I would appreciate your opinion here