docs: explain more the desired effects of `$embed_file('path')` (#8108)

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*

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.