From 9c61c52dc52f30095a9a278bd08624a794a077a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Moya?= <andres.moya@kaleidos.net>
Date: Wed, 23 Sep 2020 09:28:31 +0200
Subject: [PATCH] :books: Improve frontend debugging documentation

---
 docs/02-Frontend-Developer-Guide.md | 64 ++++++++++++++++++++++-------
 frontend/src/app/util/debug.cljs    |  6 ++-
 2 files changed, 55 insertions(+), 15 deletions(-)

diff --git a/docs/02-Frontend-Developer-Guide.md b/docs/02-Frontend-Developer-Guide.md
index 57b1db8a3..edcfef8d5 100644
--- a/docs/02-Frontend-Developer-Guide.md
+++ b/docs/02-Frontend-Developer-Guide.md
@@ -4,19 +4,6 @@ This guide intends to explain the essential details of the frontend
 application.
 
 
-## Access to clojure from javascript console
-
-The uxbox namespace of the main application is exported, so that is
-accessible from javascript console in Chrome developer tools. Object
-names and data types are converted to javascript style. For example
-you can emit the event to reset zoom level by typing this at the
-console (there is autocompletion for help):
-
-```javascript
-app.main.store.emit_BANG_(app.main.data.workspace.reset_zoom)
-```
-
-
 ## Visual debug mode and utilities
 
 Debugging a problem in the viewport algorithms for grouping and
@@ -39,6 +26,48 @@ app.util.debug.debug_all()
 app.util.debug.debug_none()
 ```
 
+## Traces and step-by-step debugging
+
+There are some useful functions to trace program execution:
+
+```clojure
+(println "message" expression)
+  ; Outputs data to the devtools console. Clojure variables are converted to string, as in (str) function.
+```
+
+```clojure
+(js/console.log "message" (clj->js expression))
+  ; Clojure values are converted to equivalent js objects, and displayed as a foldable widget in console.
+```
+
+```clojure
+(:require [cljs.pprint :refer [pprint]])
+(pprint expression)
+  ; Outputs a clojure value as a string, nicely formatted and with data type information.
+```
+
+Also we can insert breakpoints in the code with this function:
+
+```clojure
+(js-debugger)
+```
+
+You can also set a breakpoint from the sources tab in devtools. One way of locating a source file is to
+output a trace with (js/console.log) and then clicking in the source link that shows in the console.
+
+
+## Access to clojure from javascript console
+
+The uxbox namespace of the main application is exported, so that is
+accessible from javascript console in Chrome developer tools. Object
+names and data types are converted to javascript style. For example
+you can emit the event to reset zoom level by typing this at the
+console (there is autocompletion for help):
+
+```javascript
+app.main.store.emit_BANG_(app.main.data.workspace.reset_zoom)
+```
+
 
 ## Debug state and objects
 
@@ -57,11 +86,18 @@ any complex object. To use them from clojure:
 
 But last ones are most commonly used from javscript console:
 
-```
+```javascript
 app.main.store.dump_state()
 app.main.store.dump_objects()
 ```
 
+And we have also exported `pprint` and `clj->js` functions for the console:
+
+```javascript
+pp(js_expression) // equivalent to cljs.pprint.pprint(js_expression)
+dbg(js_expression) // equivalent to cljs.core.clj__GT_js(js_expression)
+```
+
 
 ## Icons & Assets
 
diff --git a/frontend/src/app/util/debug.cljs b/frontend/src/app/util/debug.cljs
index 5269b8634..c562b1b3f 100644
--- a/frontend/src/app/util/debug.cljs
+++ b/frontend/src/app/util/debug.cljs
@@ -1,5 +1,6 @@
 (ns app.util.debug
-  "Debugging utils")
+  "Debugging utils"
+  (:require [cljs.pprint :refer [pprint]]))
 
 (def debug-options #{:bounding-boxes :group :events :rotation-handler :resize-handler :selection-center #_:simple-selection})
 
@@ -37,4 +38,7 @@
    (js/console.log str (clj->js val))
    val))
 
+(when (exists? js/window)
+  (set! (.-dbg ^js js/window) clj->js)
+  (set! (.-pp ^js js/window) pprint))