From 8430279ef4767593e9e4e472420c3354b7b225b6 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Mon, 19 Aug 2024 14:50:53 -0400
Subject: [PATCH] Document struct(secret)

---
 docs/structs.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/structs.md b/docs/structs.md
index 4ab78fe..842f815 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"
+```