Document struct(secret)

1 files changed, 39 insertions, 0 deletions

diff --git a/docs/structs.md b/docs/structs.md
index 4ab78fed..842f815b 100644
--- a/docs/structs.md
+++ b/docs/structs.md
@@ -37,3 +37,42 @@ my_foo:get_older()
 
 Method calls work when the first argument is the struct type or a pointer to
 the struct type.
+
+## Secret Values
+
+If you want to prevent accidental leaking of sensitive information, you can
+create a struct with the `secret` flag turned on, which causes the struct to
+be converted to text without showing any of its contents:
+
+```tomo
+struct Password(raw_password_text:Text; secret)
+struct User(username:Text, password:Password)
+...
+user := User("Stanley", Password("Swordfish"))
+>> user
+= User(username="Stanley", password=Password(...))
+
+>> "$user" == 'User(username="Stanley", password=Password(...))'
+= yes
+```
+
+Designing APIs so they take secrecy-protected structs instead of raw data
+values is a great way to prevent accidentally leaking sensitive information in
+your logs! Secrecy-protected values still work the same as any other struct,
+they just don't divulge their contents when converting to strings:
+
+```tomo
+>> user.password == Password("Swordfish")
+= yes
+```
+
+You can also access the fields directly, but hopefully this extra amount of
+friction reduces the chances of accidentally divulging sensitive content:
+
+```tomo
+>> user.password
+= Password(...)
+
+>> user.password.raw_password_text
+= "Swordfish"
+```