Update debugger topic

[octref]

Writer: @weinand
Reviewer: @roblourens

---

• Page: https://vscode-ext-docs.azurewebsites.net/api/extension-guides/debug-extension
• File to edit: https://github.com/Microsoft/vscode-docs/blob/ext-docs/api/extension-guides/debug-extension.md

The problems:

• This page does not link to the new DAP website
• This page does not include updated illustrations such as those in this blog post, making it harder to understand the purpose of DAP (solving the ide*runtime debugging problem), and the way DAP works (as illustrated in the message communication image)

Here are some inspirations, from docs I was trying to make for LSP:

• https://vscode-ext-docs.azurewebsites.net/api/language-extensions/overview#programmatic-language-features
• https://vscode-ext-docs.azurewebsites.net/api/language-extensions/smart-editing-lsp-guide

The todo:

• Update the page so it points to DAP website
• Use the updated illustration from the blog post to better explain DAP and the way it works
• Update the Debugger section of Extension Capabilities Overview page too. Include a short passage that explains what Debug Extension is capable of and point them to the more detailed guide. File to edit is: https://github.com/Microsoft/vscode-docs/blob/ext-docs/api/extension-capabilities/overview.md

[octref]

@weinand BTW if you want the same style of illustration on the LSP website, I can do it for you (or @misolori).

[weinand]

I've updated the Extension Guide and Extension Capabilities Overview as suggested by @octref.

@roblourens now it's your turn to review this. I suggest that you incorporate fixes and suggestions directly.

[roblourens]

I made some proofreading edits, feel free to revert or change any of them, but here are some other questions:

• I think the numbers on the first image should be larger, they are a bit hard to read, the way the image is sized on the page.
• The terms "Debug extension API" and "Debugger extension" are confusing and used inconsistently. Sometimes they are uppercased, sometimes not. Sometimes "debug" is used, sometimes "debugger". On the first page it seems to refer to the debug protocol, then on the second page, "Debug extension API" is the top level heading for talking about debug adapters, and also has "Debug extension API" as a subheading for talking about the EH API. We need consistent terminology.
• It's not clear what "Extension Protocol" refers to in the second architecture image on the first page. The package.json declarations? "Extension Protocol" as a term isn't used anywhere else on the page. There are two labels pointing at two overlaid arrows, I can't tell which is which.
• I thought we were deprecating onDebug, is there any reason to keep it when the more precise activation events exist?
• There is some duplication between the beginnings of the two sections, it seems odd that they say the same things in different ways. They both have a list of debugger features, but they are different lists, and they both mention Node.js as a showcase. Is the purpose of the Capabilities page to be a boiled-down overview of the same material from the in-depth Guide?

[roblourens]

Also, @octref I see both "Extension point" and "Contribution point" used, are those the same?

[octref]

They aren't. We should always use Contribution Point, which is explained in the beginner guide and referenced in all places.

[octref]

@weinand

The debugging part under Extension Capabilities Overview is well-written, but it's a bit too long as a sub-topic under the Overview. I moved it to a sub-topic, and put up a shorter paragraph.

Feel free to make edits, as I'm not familiar with Debug API.

The only requirement is it cannot exceed 1000 characters. The original one is 3500, new one is under 500. People on this page are still deciding on "what kind of extension should I write", so we shouldn't inundate them with DAP and other Debug Extension API details.

[octref]

Link updated: https://vscode-ext-docs.azurewebsites.net/api/extension-capabilities/overview

[weinand]

Thanks everyone for the feedback. I'll fix the documents and incorporate the suggestions.

Some comments about the "Extension Capabilities Overview":

• I have a problem with the bullet list's title "Example Extension Points". This sounds like "Contribution Point" but some items below it are not "Contribution Points" but just "Extension API". I think it would help if we could find a title that covers both extension mechanisms ("Contribution points" and "Extension API"), without using the misleading term "Point" again. E.g. "Example functionalities" (since "functionalities" is already used in the first bullet list of the document), or "Example extensibility".
• the section about "Programmatic Language Features" exceeds the 1000 character limit by 30%! ;-)

[octref]

Example Extension Points

Yes I don't like that either. I changed it to Extension Ideas. I'm reviewing the topic and will remove all references to "Extension Point".

the section about "Programmatic Language Features" exceeds the 1000 character limit by 30%! ;-)

• Alright, reduce "Programmatic Language Features" to less than 1000 characters @octref

[roblourens]

I still feel that there is too much duplication between the debugging capabilities doc, and the debugging guide. I don't think it needs to go so far in depth to explain the basic capabilities of debugger extensions in vscode, and the details of what debug adapters are, what the debug protocol is, etc, are better left to the full guide.

[weinand]

@roblourens please wait with another round of reviews until I have pushed my changes. The debugging capabilities doc is already gone, but I will push the changes only after I have fixed all the links. As usual I will announce when I'm done.

[roblourens]

Sure, just recording the outcome of a long conversation I had with @octref regarding the organization.

[weinand]

I've tried to address Rob's feedback:

• In order to make the numbers larger, I've cropped the right side of the image because no debug specific features lived there anyway.
• I've tried to make the terminology and capitalization consistent.
• I've removed the (unexplained) "Extension Protocol" label and text from the second drawing.
• deprecating the "onDebug" activation event is a valid objection that I would like to address at a later time (see Consider to deprecate onDebug activation event vscode#64035).
• by making the debugging part under Extension Capabilities Overview smaller, there is no longer duplication with the Extension Guide (and I've eliminated the sub-topic completely because that information already exists in the guide). The link in the overview refers directly to the guide now.

[weinand]

@octref please rename "Debug Extension" in the left navbar to "Debuggers" because the title of the guide is "Debugger Extension" and it seems that we do not use the redundant "Extension" in the subtopics titles.

[weinand]

I'm done with my updates.

[roblourens]

Pushed a few minor edits, I think it looks great. One last question, should all instances of launch.json be in backticks?

[gregvanl]

We use backticks for filenames so yes, it should be launch.json.

[octref]

please rename "Debug Extension" in the left navbar to "Debuggers" because the title of the guide is "Debugger Extension" and it seems that we do not use the redundant "Extension" in the subtopics titles.

Done. FYI It's easy to do, just update https://github.com/Microsoft/vscode-docs/blob/ext-docs/api/toc.json

We do have "Markdown Extension" so I think "Debugger Extension" is fine.

[octref]

by making the debugging part under Extension Capabilities Overview smaller, there is no longer duplication with the Extension Guide (and I've eliminated the sub-topic completely because that information already exists in the guide). The link in the overview refers directly to the guide now.

Removed Extension Capability / Debugging.

[octref]

For what it's worth, "Programmatic Language Features" is cut down to 732 characters.

[weinand]

Which happens to be the year of the Battle of Tours! ;-)