Repository navigation
Update debugger topic #2195
Description
Activity
Andre Weinand (@weinand) BTW if you want the same style of illustration on the LSP website, I can do it for you (or @misolori).
I've updated the Extension Guide and Extension Capabilities Overview as suggested by Pine (@octref).
roblourens now it's your turn to review this. I suggest that you incorporate fixes and suggestions directly.
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?
Also, Pine (@octref) I see both "Extension point" and "Contribution point" used, are those the same?
They aren't. We should always use
Contribution Point, which is explained in the beginner guide and referenced in all places.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.
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%! ;-)
2 remaining items
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.
Sure, just recording the outcome of a long conversation I had with Pine (@octref) regarding the organization.
- added a commit that references this issue
on Nov 29, 2018 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.
Pine (@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.
I'm done with my updates.
Pushed a few minor edits, I think it looks great. One last question, should all instances of
launch.jsonbe in backticks?We use backticks for filenames so yes, it should be
launch.json.- added a commit that references this issue
on Nov 30, 2018 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.
- added a commit that references this issue
on Dec 3, 2018 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.
For what it's worth, "Programmatic Language Features" is cut down to 732 characters.
Which happens to be the year of the Battle of Tours! ;-)
Reacted by Pine
Writer: Andre Weinand (@weinand)
Reviewer: roblourens
The problems:
Here are some inspirations, from docs I was trying to make for LSP:
The todo:
Debuggersection 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