From 7441889efe01c19617afa8c28f1fbf54d3c627a1 Mon Sep 17 00:00:00 2001
From: Larpon <Larpon@users.noreply.github.com>
Date: Thu, 14 Jan 2021 17:19:04 +0100
Subject: [PATCH] docs: explain more the desired effects of
 `$embed_file('path')` (#8108)

---
 CHANGELOG.md |  2 +-
 doc/docs.md  | 28 +++++++++++++++++++++++++++-
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 483731c49b..9078254fd7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,7 @@
 - Auto generate assignment operators like `+=`, `-=`, `*=`, `/=` and `%=` if the operators are defined.
 - Colorize and improve failing tests output.
 - Fix `go` with a generic function: `go test<string>(c, 'abcd')`.
-- Add comptime `x := $embed_file('v.png') println(x.len) println(ptr_str(x.data()))`.
+- Add comptime `x := $embed_file('v.png') println(x.len) println(ptr_str(x.data()))`, for embedding files into binaries.
 
 ## V 0.2.1
 *30 Dec 2020*
diff --git a/doc/docs.md b/doc/docs.md
index 93f9d41376..569efbd84b 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -3013,8 +3013,9 @@ use `v help`, `v help build` and `v help build-c`.
 
 ## Conditional compilation
 
-### Compile time if
+### Compile time code
 
+#### $if
 ```v
 // Support for multiple conditions in one branch
 $if ios || android {
@@ -3062,6 +3063,31 @@ Full list of builtin options:
 | `gnu`, `hpux`, `haiku`, `qnx` | `cplusplus`       | `big_endian`          | |
 | `solaris`, `linux_or_macos`   | | | |
 
+#### $embed_file
+
+```v ignore
+module main
+fn main() {
+	embedded_file := $embed_file('v.png')
+	mut fw := os.create('exported.png') or { panic(err) }
+	fw.write_bytes(embedded_file.data(), embedded_file.len)
+	fw.close()
+}
+```
+
+V can embed arbitrary files into the executable with the `$embed_file(<path>)`
+compile time call. Paths can be absolute or relative to the source file.
+
+When you do not use `-prod`, the file will not be embedded. Instead, it will
+be loaded *the first time* your program calls `f.data()` at runtime, making
+it easier to change in external editor programs, without needing to recompile
+your executable.
+
+When you compile with `-prod`, the file *will be embedded inside* your
+executable, increasing your binary size, but making it more self contained 
+and thus easier to distribute. In this case, `f.data()` will cause *no IO*,
+and it will always return the same data.
+
 ### Environment specific files
 
 If a file has an environment-specific suffix, it will only be compiled for that environment.