From 0f3b792562387dcaf0024b2da1a29166070b56f6 Mon Sep 17 00:00:00 2001
From: Denis Fakhrtdinov <me@shizz.ru>
Date: Tue, 5 Mar 2019 23:50:05 +0100
Subject: [PATCH] [#1] importers documented

---
 docs/importers.md | 37 +++++++++++++++++++++++++++++++++++++
 docs/index.md     |  3 ++-
 2 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 docs/importers.md

diff --git a/docs/importers.md b/docs/importers.md
new file mode 100644
index 0000000..581b972
--- /dev/null
+++ b/docs/importers.md
@@ -0,0 +1,37 @@
+# Importers
+
+Defining importer functions is a way to import some fancy packed data into your datastructure.
+
+Techically speaking, it is called only within `new/1` function right before the [substructures](substructures.md) initialization if any.
+
+You may declare a function called `on_import_FIELD_NAME` with the following spec:
+
+```erlang
+-spec on_import_FIELD_NAME(InValue :: term()) ->
+    OutValue :: term() | no_return().
+```
+
+For example, if the original map contains a structured binary value under the `binary` field, the following function will automatically transform it to map:
+
+```erlang
+on_import_binary(<<Length:16, Value:Length/binary>>) ->
+    #{
+        length => Length,
+        value => Value 
+    };
+on_import_binary(_) ->
+    error(badarg).
+```
+
+If you will then define a [substructure](substructures.md) for this field, a substructure constructor will be automatically called, and only then the value will be [validated](validators.md).
+
+You may refer to the [`priv_callbacks_on_import.erl`](/test/priv/priv_callbacks_on_import.erl) modified source code to understand what happens when you're declaring the importer:
+
+```erlang
+i_on_import(a, Var_value_0) ->
+    on_import_a(Var_value_0);
+i_on_import(_, Var_value_0) ->
+    Var_value_0.
+```
+
+Please, refer to [Exporters](exporters.md) documentation to find a way to pack your data back into binary.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 5022a29..01fff7a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,10 +3,11 @@
 * [Compile-time options](compile-time-options.md): a set of options that may be used to change `cloak` behavior at compile-time
 * [Field types](field-types.md): description of different field types `cloak` supports
 * [Runtime errors](runtime-errors.md): runtime errors `cloak` can generate
-* [Internal functions](internal-functions.md): description of auto-generated internal functions that you may use in your source code
 * [Importers](importers.md): a way to import some fancy-packed data into your datastructure
 * [Validators](validators.md): different ways to validate data with user-defined callbacks
 * [Exporters](exporters.md): different ways to export data with user-defined callbacks
 * [Substructures](substructures.md): explanation of nested data structures `cloak` supports
+* [Internal functions](internal-functions.md): description of auto-generated internal functions that you may use in your source code
+* [Tips and tricks](tips and tricks.md)
 * [Known issues](known-issues.md)
 * [Contributing](contributing.md)