1 files changed, 26 insertions, 2 deletions
diff --git a/doc/DESIGN.md b/doc/DESIGN.md
index 7781cd1..fae9ef2 100644
--- a/doc/DESIGN.md
+++ b/doc/DESIGN.md
@@ -62,7 +62,7 @@ const main = fn() !void {
 
     var str1 = "hello";
     var str2 = "world";
-    var str3 = try str1 + " " + str2;
+    var str3 = try str1 + " " + str2; // `try` is needed here, because str concat can fail
     var str4 = try str1 + 20; // error, can't add number to string. Preferable use str.fmt or explicitly cast to string
     var str5 = try str1 + str(20); // ok, number explicitly cast to string
 
@@ -144,6 +144,30 @@ const main = fn {
 }
 ```
 
+## Encapsulation
+By default declared data can't be used outside the file they were declared in. To make the declared data accessible
+from other files you can use the `pub` keyword.
+json.amal
+```
+pub const Object = struct {
+    // fields...
+}
+
+pub const to_object = fn(data: &str) Object {
+    // code to convert string to Object...
+}
+```
+
+main.amal:
+```
+const json = @import("json.amal");
+
+const main = fn {
+    // Type is json.Object
+    var json_obj = json.to_object("{ \"key\": 42 }");
+}
+```
+
 ## Generic programming
 ```
 const add = fn(comptime T: type, a: T, b: T) !T {
@@ -163,7 +187,7 @@ Rust doesn't handle this but Amalgam does it using #reallocatable(instance).
 Reallocatable should be ignored if the reference that taken from the reallocatable memory
 doesn't change location after realloc, which would be the case for pointers.
 ```
-const ArrayList = @import("std.array.ArrayList")
+const ArrayList = @import("std.array.ArrayList");
 
 const User = struct {
     name: str,