📚 Update docs.

common/uxbox/common/pages.cljc

@@ -186,7 +186,7 @@
 
 (defmethod process-change :add-obj
   [data {:keys [id obj frame-id index] :as change}]
-  (us/assert! (contains? (:objects data) frame-id) "process-change/add-obj")
+  (assert (contains? (:objects data) frame-id) "process-change/add-obj")
   (let [obj (assoc obj
                    :frame-id frame-id
                    :id id)]
@@ -220,13 +220,13 @@
 
 (defmethod process-change :mod-obj
   [data {:keys [id operations] :as change}]
-  (us/assert! (contains? (:objects data) id) "process-change/mod-obj")
+  (assert (contains? (:objects data) id) "process-change/mod-obj")
   (update-in data [:objects id]
              #(reduce process-obj-operation % operations)))
 
 (defmethod process-change :mov-obj
   [data {:keys [id frame-id] :as change}]
-  (us/assert! (contains? (:objects data) frame-id))
+  (assert (contains? (:objects data) frame-id))
   (let [frame-id' (get-in data [:objects id :frame-id])]
     (when (not= frame-id frame-id')
       (-> data

common/uxbox/common/spec.cljc

@@ -110,27 +110,12 @@
 
 ;; --- Macros
 
-(defmacro assert!
-  "Evaluates expr and throws an exception if it does not evaluate to
-  logical true."
-  ([x]
-   (when *assert*
-     `(when-not ~x
-        (throw (ex/error :type :assertion-error
-                         :hint (str "Assert failed: " (pr-str '~x)))))))
-  ([x message]
-   (when *assert*
-     `(when-not ~x
-        (throw (ex/error :type :assertion-error
-                         :hint (str "Assert failed: " (pr-str '~x))
-                         :message ~message))))))
-
 (defn spec-assert
   [spec x]
   (s/assert* spec x))
 
 (defmacro assert
-  "Always active assertion macro (does not obey to :elide-asserts)"
+  "Development only assertion macro."
   [spec x]
   (when *assert*
     `(spec-assert ~spec ~x)))

docs/01-Development-Environment.md

@@ -8,7 +8,7 @@ The main development environment consists in a docker compose
 configuration that starts the external services and the development
 container (called **devenv**).
 
-We use tmux script in order to multiplex the signle terminal and run
+We use tmux script in order to multiplex the single terminal and run
 both the backend and frontend in the same container.
 
 
@@ -77,22 +77,19 @@ The backend related environment is located in the tmux **window 2**,
 and you can go directly to it using `ctrl+b 2` shortcut.
 
 By default the backend will be started in non-interactive mode for
-convenience but you can just press `Ctrl+c` and execute `clojure
--J-XX:-OmitStackTraceInFastThrow -Adev:repl` for start the repl.
-
+convenience but you can just press `Ctrl+c` and execute `./bin/repl`
+for start the repl.
 
 On the REPL you have this helper functions:
 - `(start)`: start all the environment
 - `(stop)`: stops the environment
 - `(restart)`: stops, reload and start again.
 
+And many other that are defined in the `tests/user.clj` file.
+
 If some exception is raised when code is reloaded, just use
 `(repl/refresh-all)` in order to finish correctly the code swaping and
 later use `(restart)` again.
 
-
-If this is your first run, you maybe want to load fixtures first:
-`(load-fixtures)`.
-
 For more information, please refer to: `03-Backend-Guide.md`.
 

docs/02-Frontend-Developer-Guide.md

@@ -6,6 +6,28 @@ application.
 **TODO**
 
 
+## Icons & Assets
+
+The icons used on the frontend application are loaded using svgsprite
+(properly handled by the gulp watch task). All icons should be on SVG
+format located in `resources/images/icons`. The gulp task will
+generate the sprite and the embedd it into the `index.html`.
+
+Then, you can reference the icon from the sprite using the
+`uxbox.builtins.icons/icon-xref` macro:
+
+```clojure
+(ns some.namespace
+  (:require-macros [uxbox.builtins.icons :refer [icon-xref]]))
+
+(icon-xref :arrow)
+```
+
+For performance reasons, all used icons are statically defined in the
+`src/uxbox/buitings/icons.cljs` file.
+
+
+
 ## Translations (I18N) ##
 
 ### How it Works ###

docs/04-Common-Developer-Guide.md

@@ -6,13 +6,9 @@ and backend, such as: code style hints, architecture dicisions, etc...
 
 ## Assertions ##
 
-UXBOX source code has 3 types of assertions that can be used: simple,
-spec, and dev-spec.
+UXBOX source code has this types of assertions:
 
-The simple assertion consists in using the clojure builting `assert`
-macro. This asserts are only executed on development mode. On
-production environment all assets like this will be ignored by
-runtime.
+**assert**: just using the clojure builtin `assert` macro.
 
 Example:
 
@@ -20,6 +16,11 @@ Example:
 (assert (number? 3) "optional message")
 ```
 
+This asserts are only executed on development mode. On production
+environment all assets like this will be ignored by runtime.
+
+**spec/assert**: using the `uxbox.common.spec/assert` macro.
+
 Also, if you are using clojure.spec, you have the spec based
 `clojure.spec.alpha/assert` macro. In the same way as the
 `clojure.core/assert`, on production environment this asserts will be
@@ -28,25 +29,33 @@ removed by the compiler/runtime.
 Example:
 
 ````clojure
-(require '[clojure.spec.alpha :as s])
+(require '[clojure.spec.alpha :as s]
+         '[uxbox.common.spec :as us])
 
 (s/def ::number number?)
 
-(s/assert ::number 3)
+(us/assert ::number 3)
 ```
 
-And finally, for cases when you want a permanent assert (including in
-production code), you need to use `uxbox.common.spec/assert` macro. It
-has the same call signature as `clojure.spec.alpha/assert`.
+In the same way as the `assert` macro, this performs the spec
+assertion only on development build. On production this code will
+completely removed.
+
+**spec/verify**: An assertion type that is executed always.
 
 Example:
 
 ```clojure
 (require '[uxbox.common.spec :as us])
 
-(us/assert ::number 3)
+(us/verify ::number 3)
 ```
 
 This macro enables you have assetions on production code.
 
+**Why don't use the `clojure.spec.alpha/assert` instead of the `uxbox.common.spec/assert`?**
+
+The uxbox variant does not peforms additional runtime checks for know
+if asserts are disabled in "runtime". As a result it generates much
+simplier code at development and production builds.