From 535a9dd582ae675008984c694a97674bb97a5a3b Mon Sep 17 00:00:00 2001
From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
Date: Thu, 24 Aug 2023 22:43:33 -0700
Subject: [PATCH] Add doc comments about why symbol_short! (#1064)

### What
Add doc comments about why symbol_short! is preferred over
Symbol::short.

### Why
The behavior of const functions when called in non-const-contexts is not
well known, as has been evidenced by the many times folks have asked why
we have symbol_short!, and the case where symbol_short! was removed with
folks assuming it was of no use. For example:
https://github.com/stellar/rs-soroban-sdk/pull/1043#discussion_r1276653494.
Adding docs to knowledge share.
---
 soroban-sdk/src/symbol.rs | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/soroban-sdk/src/symbol.rs b/soroban-sdk/src/symbol.rs
index 459a122c9..7ed64b1f3 100644
--- a/soroban-sdk/src/symbol.rs
+++ b/soroban-sdk/src/symbol.rs
@@ -209,7 +209,30 @@ impl Symbol {
     ///
     /// Valid characters are `a-zA-Z0-9_` and maximum length is 9 characters.
     ///
-    /// The conversion can happen at compile time.
+    /// The conversion can happen at compile time if called in a const context,
+    /// such as:
+    ///
+    /// ```rust
+    /// # use soroban_sdk::Symbol;
+    /// const SYMBOL: Symbol = Symbol::short("abcde");
+    /// ```
+    ///
+    /// Note that when called from a non-const context the conversion will occur
+    /// at runtime and the conversion logic will add considerable number of
+    /// bytes to built wasm file. For this reason the function should be generally
+    /// avoided:
+    ///
+    /// ```rust
+    /// # use soroban_sdk::Symbol;
+    /// let SYMBOL: Symbol = Symbol::short("abcde"); // AVOID!
+    /// ```
+    ///
+    /// Instead use the `symbol_short!()` macro that will ensure the conversion always occurs in a const-context:
+    ///
+    /// ```rust
+    /// # use soroban_sdk::{symbol_short, Symbol};
+    /// let SYMBOL: Symbol = symbol_short!("abcde"); // 👍
+    /// ```
     ///
     /// ### Panics
     ///