Update debugger documentation (#2471)

The documentation has not been updated when the HTML client got
removed nor when the new transport layer replaced the previous
debug server initialization process.

JerryScript-DCO-1.0-Signed-off-by: Akos Kiss akiss@inf.u-szeged.hu

docs/07.DEBUGGER.md

@@ -3,11 +3,11 @@
 JerryScript provides a remote debugger which allows debugging
 JavaScript programs. The debugger has two main components:
 a server which is part of the JerryScript binary and a
-separate client application. Currently two debugger clients
+separate client application. Currently a Python-based debugger
-are available in the /jerry-debugger subdirectory: an HTML
+client is available in the /jerry-debugger subdirectory.
-and a Python application. These simple applications demonstrate
+This simple application demonstrates the communication protocol
-the communication protocol between the client and server and can
+between the client and server, and can be reused by integrated
-be reused by integrated development environments.
+development environments.
 
 ## Setting up the debugger server
 
@@ -15,12 +15,13 @@ The following arguments must be passed to `tools/build.py`:
 
 `--jerry-debugger=on --jerry-libc=off`
 
-At the moment only a Websocket-based implementation is provided
+The transport layer of the communication protocol is pluggable.
-by JerryScript which transmits messages over TCP/IP networks.
+At the moment, a WebSocket-based implementation is provided as a
+JerryScript extension, which transmits messages over TCP/IP networks.
 This implementation requires a socket API which is not yet
 supported by jerry-libc so the standard libc is used instead.
-In the future any reliable stream or datagram based protocol
+If necessary/implemented, any reliable stream or datagram based
-can be used for transmitting debugger messages.
+protocol can be used for transmitting debugger messages.
 
 ## Debugging JavaScript applications
 
@@ -49,8 +50,8 @@ the *Waiting for client connection* message:
 
 `--log-level 2`
 
-The HTML client can connect to the IP address of the server with
+The Python client can connect to the server by specifying its
-the `connect` command. The IP address can be localhost
+IP address on the command line. The address can be localhost
 if the server and the client are running on the same machine.
 
 After the connection is established the execution can be
@@ -65,9 +66,12 @@ All available commands of the client can be queried by the
 
 ## Integrating debugger support into applications using JerryScript
 
-The debugger can be enabled by calling the `jerry_debugger_init (uint16_t port)`
+When using the extension-provided WebSocket transport layer, the
-function after the `jerry_init ()` function. It initializes the debugger
+debugger can be enabled by calling `jerryx_debugger_after_connect
-and blocks until a client connects.
+(jerryx_debugger_tcp_create (debug_port) && jerryx_debugger_ws_create ())`
+after the `jerry_init ()` function. It initializes the debugger and
+blocks until a client connects. (Custom transport layers may be
+implemented and initialized similarly.)
 
 The resource name provided to `jerry_parse ()` is used by the client
 to identify the resource name of the source code. This resource name
@@ -76,7 +80,7 @@ is usually a file name.
 ## JerryScript debugger C-API interface
 
 The following section describes the debugger functions
-available for the host application.
+available to the host application.
 
 ## JerryScript debugger types
 
@@ -107,36 +111,6 @@ typedef jerry_value_t
 
 ## JerryScript debugger functions
 
-### jerry_debugger_init
-
-**Summary**
-
-Debugger server initialization. Must be called after `jerry_init`.
-
-**Prototype**
-
-```c
-void
-jerry_debugger_init (uint16_t port);
-```
-
-- `port` - Server port number
-
-
-**Example**
-
-```c
-{
-  jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
-
-  // ...
-
-  jerry_cleanup ();
-}
-```
-
-
 ### jerry_debugger_is_connected
 
 **Summary**
@@ -155,7 +129,8 @@ jerry_debugger_is_connected (void);
 ```c
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   if (jerry_debugger_is_connected ())
   {
@@ -187,7 +162,8 @@ jerry_debugger_stop (void)
 ```c
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   jerry_debugger_stop ();
 
@@ -221,7 +197,8 @@ jerry_debugger_continue (void)
 ```c
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   jerry_debugger_continue ();
 
@@ -233,7 +210,7 @@ jerry_debugger_continue (void)
 
 - [jerry_debugger_stop](#jerry_debugger_stop)
 
-### jerry_debugger_disable_stop_at_breakpoint
+### jerry_debugger_stop_at_breakpoint
 
 **Summary**
 
@@ -255,7 +232,8 @@ jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint)
 ```c
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   jerry_debugger_stop_at_breakpoint (true);
 
@@ -323,7 +301,8 @@ int main ()
      * received. Applications usually registers their core bindings
      * here as well (e.g. print, setTimeout). */
     jerry_init (JERRY_INIT_EMPTY);
-    jerry_debugger_init (5001);
+    jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                   && jerryx_debugger_ws_create ());
 
     do
     {
@@ -368,7 +347,8 @@ jerry_debugger_send_output (jerry_char_t buffer[], jerry_size_t string_size)
 ```c
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   jerry_char_t my_output = "Hey, this should be sent too!";
   jerry_size_t my_output_size = sizeof (my_output);
@@ -397,7 +377,8 @@ jerry_debugger_send_log (jerry_log_level_t level, jerry_char_t buffer[], jerry_s
 ```c
 {
   jerry_init (JERRY_INIT_EMPTY);
-  jerry_debugger_init (5001);
+  jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001)
+                                 && jerryx_debugger_ws_create ());
 
   jerry_char_t my_log = "Custom diagnostics";
   jerry_size_t my_log_size = sizeof (my_log);

jerry-debugger/README.md

@@ -1,5 +1,5 @@
-# Available jerryscript debugger tools
+# Available JerryScript debugger tools
 
-JerryScript console debugger client ( jerry-client-ws.py )  
+  - JerryScript console debugger client ( jerry_client.py )
-Iotjscode ( https://github.com/Samsung/iotjscode )  
+  - IoT.js Code ( https://github.com/Samsung/iotjscode )
-Jerryscript debugger Chrome webtool ( https://github.com/jerryscript-project/jerryscript-debugger-ts )
+  - JerryScript debugger Chrome webtool ( https://github.com/jerryscript-project/jerryscript-debugger-ts )