Document opaque types

Closes https://github.com/gleam-lang/language-tour/issues/63

2 files changed, 33 insertions, 0 deletions

diff --git a/src/content/chapter5_advanced_features/lesson07_multi_target_externals/code.gleam b/src/content/chapter5_advanced_features/lesson07_multi_target_externals/code.gleam
new file mode 100644
index 0000000..b62a735
--- /dev/null
+++ b/src/content/chapter5_advanced_features/lesson07_multi_target_externals/code.gleam
@@ -0,0 +1,11 @@
+import gleam/io
+
+pub type DateTime
+
+@external(erlang, "calendar", "local_time")
+@external(javascript, "./my_package_ffi.mjs", "now")
+pub fn now() -> DateTime
+
+pub fn main() {
+  io.debug(now())
+}
diff --git a/src/content/chapter5_advanced_features/lesson07_multi_target_externals/en.html b/src/content/chapter5_advanced_features/lesson07_multi_target_externals/en.html
new file mode 100644
index 0000000..6e02d36
--- /dev/null
+++ b/src/content/chapter5_advanced_features/lesson07_multi_target_externals/en.html
@@ -0,0 +1,22 @@
+<p>
+  Multiple external implementations can be specified for the same function,
+  enabling the function to work on both Erlang and JavaScript.
+</p>
+<p>
+  If a function doesn't have an implementation for the currently compiled-for
+  target then the compiler will return an error.
+</p>
+<p>
+  You should try to implement functions for all targets, but this isn't always
+  possible due to incompatibilities in how IO and concurreny works in Erlang and
+  JavaScript. With Erlang concurrent IO is handled transparently by the runtime,
+  while in JavaScript concurrent IO requires the use of promises or callbacks.
+  If your code uses the Erlang style it is typically not possible to implement
+  in JavaScript, while if callbacks are used then it won't be compatible with
+  most Gleam and Erlang code as it forces any code that calls the function to
+  also use callbacks.
+</p>
+<p>
+  Libraries that make use of concurrent IO will typically have to decide whether
+  they support Erlang or JavaScript, and document this in their README.
+</p>