Merge pull request #91 from ManuelHentschel/documentation

Documentation

Author: ManuelHentschel

.vscodeignore

@@ -3,8 +3,8 @@
 out/test/**
 src/**
 .gitignore
-vsc-extension-quickstart.md
 **/tsconfig.json
 **/.eslintrc.json
 **/*.map
 **/*.ts
+test/**

configuration.md

@@ -45,7 +45,7 @@ The intended usecases for these modes are:
 R Files can be run by focussing a file and pressing `F5`.
 The stack view contains a single dummy frame.
 To view the variables in the global environment it is often necessary to click this frame and expand the variables view!
-This method is 'abusing' the debug adapter protocol to some extent, since the protocol is apparently not designed for ongoing interactive programming in a global workspace.
+This method is 'abusing' the debug adapter protocol to some extent, since the protocol is not designed for ongoing interactive programming in a global workspace.
 * `"file"`: Is pretty much equivalent to launching the debugger with `"workspace"` and immediately calling `.vsc.debugSource()` on a file.
 Is hopefully the behaviour expected by users coming from R Studio etc.
 * `"function"`: The above debug modes introduce significant overhead by passing all input through `eval()` etc.
@@ -69,14 +69,12 @@ Usually, specifying individual packages in `debuggedPackages` is preferred.
 * `"includePackageScopes"`: Set to `true` to view the exported functions/variables of packages in the variable view.
 * `"debuggedPackages"`: List of package names to be debugged.
 These packages are loaded before running the specified file/function.
-Breakpoints and the modified `print`/`cat`/`message` functions are applied in these packages.
-* `"overwritePrint"`: Whether to overwrite the `print` function with a custom version
-that also prints a link to the file and line number in the debug console.
-This overwrite does not affect print statements in packages.
+Breakpoints and the modified `print`/`cat`/`message`/`str` functions are applied in these packages.
+* `"overwritePrint"`: Whether to attach a custom `print` function that also prints a link to the file and line number in the debug console.
 * `"overwriteCat"`: Same as above for `cat()`
+* `"overwriteStr"`: Same as above for `str()`.
 * `"overwriteMessage"`: Same as above for `message()`
-* `"overwriteSource"`: Whether to overwrite the `source` function with a custom version
-that is affected by breakpoints set in VS Code.
+* `"overwriteSource"`: Whether to overwrite the `source` function with a custom version that is affected by breakpoints set in VS Code.
 
 
 ## 4. R Options
@@ -105,6 +103,7 @@ If no values are set, the defaults listed below are used.
 * `"vsc.defaultOverwriteMessage" = TRUE` Default value for the launch config entry `overwriteMessage`
 * `"vsc.defaultOverwritePrint" = TRUE` Default value for the launch config entry `overwritePrint`
 * `"vsc.defaultOverwriteSource" = TRUE` Default value for the launch config entry `overwriteSource`
+* `"vsc.defaultOverwriteStr" = TRUE` Default value for the launch config entry `overwriteStr`
 * `"vsc.defaultSetBreakpointsInPackages" = FALSE` Default value for the launch config entry `setBreakpointsInPackages`
 * `"vsc.dropArrays" = TRUE`: Whether to skip dimensions of size one when showing arrays in the variables window
 * `"vsc.evaluateActiveBindings" = FALSE`: Whether to evaluate active bindings and show the value in the variables view

readme.md

@@ -19,7 +19,7 @@ For many variables it is also possible to assign a new value to the variable or
 5. Set breakpoints and break on errors.
 6. Control the program flow using *step*, *step in*, *step out*, *continue*.
 7. Output generated by the program is printed to the debug console (filtering out text printed by the browser itself).
-8. The debugger adds a modified version of `print` and `cat` that also print a link to the file and line where the text was printed.
+8. The debugger adds a modified version of `print`, `cat`, `message`, and `str` that also print a link to the file and line where the text was printed.
 9. The debug console allows the execution of arbitrary R code in the currently selected stack frame.
 
 
@@ -31,8 +31,8 @@ After installing the extension, the R package can be installed using the command
 If this does not work, you can find the source code and compiled binaries on the
 [releases site](https://github.com/ManuelHentschel/VSCode-R-Debugger/releases).
 
-The provided binaries were compiled using R 4.0.2 and might be incompatible with older R versions.
-In these cases it is necessary to compile the package from code.
+The provided packages were built using R 4.0.2 and might be incompatible with older R versions.
+In these cases it is necessary to build the package from code.
 
 If you want to install a development version, the VS Code extension can be installed from the .vsix-files found 
 [here](https://github.com/ManuelHentschel/VSCode-R-Debugger/actions?query=workflow%3Amain).
@@ -43,6 +43,13 @@ To install the latest development version of the required R-package from GitHub,
 or install from the artifacts found 
 [here](https://github.com/ManuelHentschel/vscDebugger/actions).
 
+**Note on the package version:**
+Since the debugger is still under initial development, both this extension and the accompanying R package are major version 0.y.z.
+The minor version (x.Y.z) is incremented when backward incompatible changes to the interface/communication between the VS Code extension and the R package are introduced.
+Compatibility between the two is only intended ("guaranteed") if both have the same minor version.
+The patch version (x.y.Z) is incremented independently for all other changes that justify a new release.
+
+
 ## Using the Debugger
 * Install this extension in VS Code.
 * Install the package [**vscDebugger**](https://github.com/ManuelHentschel/vscDebugger) in R.