From d751aade99a3d8ec2a61ccc38c3e087eaaf8a5d9 Mon Sep 17 00:00:00 2001
From: Chris Mounce <christophermounce@gmail.com>
Date: Thu, 10 Jul 2025 22:13:34 -0700
Subject: [PATCH] Document purposes of functions in encoding.rs

---
 src/encoding.rs | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/encoding.rs b/src/encoding.rs
index 24b55ac..b9a0f66 100644
--- a/src/encoding.rs
+++ b/src/encoding.rs
@@ -1,7 +1,8 @@
 use anyhow::{Result, anyhow};
 use codepage_437::CP437_WINGDINGS;
 
-// Serialize multi-line content with CR-terminated lines
+/// Serialize a multi-line code string for an object or a scroll.
+/// Uses ZZT's convention of CR-terminated lines.
 pub fn encode_multiline(input: &str) -> Result<Vec<u8>> {
     input
         .chars()
@@ -17,6 +18,7 @@ pub fn encode_multiline(input: &str) -> Result<Vec<u8>> {
         .collect()
 }
 
+/// Deserialize a multi-line code string.
 pub fn decode_multiline(input: &[u8]) -> String {
     input
         .iter()
@@ -30,6 +32,8 @@ pub fn decode_multiline(input: &[u8]) -> String {
         .collect()
 }
 
+/// Serialize a single-line string for a board title.
+/// Newlines cannot be encoded because ZZT interprets them as dingbats (♪).
 pub fn encode_oneline(input: &str) -> Result<Vec<u8>> {
     input
         .chars()
@@ -41,6 +45,7 @@ pub fn encode_oneline(input: &str) -> Result<Vec<u8>> {
         .collect()
 }
 
+/// Deserialize a board title.
 pub fn decode_oneline(input: &[u8]) -> String {
     input.iter().map(|&x| CP437_WINGDINGS.decode(x)).collect()
 }
@@ -86,12 +91,12 @@ mod tests {
     }
 
     #[test]
-    fn byte_13_to_wingding() {
+    fn byte_13_to_dingbat() {
         // Code is allowed to have newlines
         let bytes = serialize_code("ABC\nDEF");
         assert!(bytes.contains(&13));
 
-        // But in a board title, that same byte is a wingding
+        // But in a board title, that same byte is a dingbat
         assert_debug_snapshot!(decode_oneline(&bytes), @r#""ABC♪DEF""#);
     }