Documentation for Source File Concerns?

[Eric Robinson]

I've been perusing the source files in this project to get a better understanding of the structure of a Debugger Extension implementation. One thing that has been a constant source of frustration is trying to divine what the role is for each main file in the repository. Specifically I'm referring to:

• extension.ts
• mockDebug.ts
• mockRuntime.ts

Unless I've straight-up missed something (please advise if I have!), I can't find anything that offers any sort of codebase orientation.

I think it would be extremely helpful to have documentation around what each class/module in the repository does; what it's role is in providing debugger features. I imagine such documentation would be available in a ReadMe.md, perhaps even directly within the src folder. Or, perhaps, in documentation comments above each of the main classes in the repository.

Another way to put it, I guess, is that this repository is missing an architecture overview.

[Andre Weinand]

@ericdrobinson here are some brief descriptions of the three files:

• mockRuntime.ts is a hypothetical (aka "Mock") "execution engine with debugging support": it takes a Markdown (*.md) file and "executes" it by "running" through the text lines and searching for "command" patterns that trigger something (e.g. exceptions). When it finds a command it typically emits an event. The runtime can not only run through the whole file but also execute one line at a time and stop on lines for which a breakpoint has been registered. This functionality is the core of the "debugging support". Since the MockRuntime is completely independent from VS Code or the Debug Adapter Protocol, it can be viewed as a simplified representation of a real "execution engine" (e.g. node.js) or debugger (e.g. gdb). When implementing your own debugger extension for VS Code, you probably don't need this class because you can rely on some existing debugger or runtime.
• mockDebug.ts contains the Debug Adapter that "adapts" or translates the Debug Adapter Protocol used by the client (e.g. VS Code) into requests and events of the real "execution engine" or "debugger" (here: MockRuntime). The most important class of the Debug Adapter is the MockDebugSession. Since the Debug Adapter is independent from VS Code, it can be used in other clients (IDEs) supporting the Debug Adapter Protocol. When implementing your own debugger extension for VS Code, most of your work will go into the Debug Adapter.
• extension.ts is the "plugin" that plugs into VS Code and contains the code that connects VS Code with the Debug Adapter. Since extension code heavily relies on VS Code APIs it depends on VS Code and cannot run in other IDEs. All VS Code extensions have an extension.ts. For Mock Debug extension.ts contains sample code for launching the Debug Adapter in three different ways: as an external program communicating with VS Code via stdin/stdout, as a server process communicating with VS Code via sockets or named pipes, or as inlined code running in the extension itself. Since the latter setup is the easiest to debug, it is the default.

I will paste the descriptions into the respective files...

[Eric Robinson]

@weinand Thank you very much! That provides a lot of helpful direction!