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

Author: akosthekiss

docs/07.DEBUGGER.md

@@ -3,24 +3,25 @@
 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
-are available in the /jerry-debugger subdirectory: an HTML
-and a Python application. These simple applications demonstrate
-the communication protocol between the client and server and can
-be reused by integrated development environments.
+separate client application. Currently a Python-based debugger
+client is available in the /jerry-debugger subdirectory.
+This simple application demonstrates the communication protocol
+between the client and server, and can be reused by integrated
+development environments.
 
 ## Setting up the debugger server
 
 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
-by JerryScript which transmits messages over TCP/IP networks.
+The transport layer of the communication protocol is pluggable.
+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
-can be used for transmitting debugger messages.
+If necessary/implemented, any reliable stream or datagram based
+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 `connect` command. The IP address can be localhost
+The Python client can connect to the server by specifying its
+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)`
-function after the `jerry_init ()` function. It initializes the debugger
-and blocks until a client connects.
+When using the extension-provided WebSocket transport layer, the
+debugger can be enabled by calling `jerryx_debugger_after_connect
+(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 )  
-Iotjscode ( https://github.com/Samsung/iotjscode )  
-Jerryscript debugger Chrome webtool ( https://github.com/jerryscript-project/jerryscript-debugger-ts )
+  - JerryScript console debugger client ( jerry_client.py )
+  - IoT.js Code ( https://github.com/Samsung/iotjscode )
+  - JerryScript debugger Chrome webtool ( https://github.com/jerryscript-project/jerryscript-debugger-ts )