From e176daa4dc392dd32ce2e4aedd89fe6d4e3ba8b6 Mon Sep 17 00:00:00 2001
From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
Date: Sat, 14 Dec 2024 02:24:16 +1000
Subject: [PATCH] Improve deploy docs (#1416)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

### What
Remove the `let _ = deployer.deployed_address();` line from the two
existing deploy examples that are in the rust docs, and add an example
that discusses the `deployer.deployed_address()` in more detail.

<img width="948" alt="Screenshot 2024-12-13 at 11 07 22 pm"
src="https://github.com/user-attachments/assets/14735e0a-a32e-46ff-9e66-ff7ee21bdc6f"
/>

### Why
Plopping the `let _ = deployer.deployed_address();` into the middle of
an example that's about a specific scenario is distracting as to the
main purpose of the example. The docs can show how to use the function
in an example focused on it specifically.
---
 soroban-sdk/src/deploy.rs | 54 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 47 insertions(+), 7 deletions(-)

diff --git a/soroban-sdk/src/deploy.rs b/soroban-sdk/src/deploy.rs
index b47d33edd..b57db93e3 100644
--- a/soroban-sdk/src/deploy.rs
+++ b/soroban-sdk/src/deploy.rs
@@ -17,19 +17,20 @@
 //! use soroban_sdk::{contract, contractimpl, BytesN, Env, Symbol};
 //!
 //! const DEPLOYED_WASM: &[u8] = include_bytes!("../doctest_fixtures/contract.wasm");
+//!
 //! #[contract]
 //! pub struct Contract;
+//!
 //! #[contractimpl]
 //! impl Contract {
 //!     pub fn deploy(env: Env, wasm_hash: BytesN<32>) {
 //!         let salt = [0u8; 32];
 //!         let deployer = env.deployer().with_current_contract(salt);
-//!         // Deployed contract address is deterministic and can be accessed
-//!         // before deploying the contract.
-//!         let _ = deployer.deployed_address();
 //!         let contract_address = deployer.deploy_v2(wasm_hash, ());
+//!         // ...
 //!     }
 //! }
+//!
 //! #[test]
 //! fn test() {
 //! # }
@@ -46,27 +47,29 @@
 //! # fn main() { }
 //! ```
 //!
-//! //! #### Deploy a contract with a multi-argument constructor
+//! #### Deploy a contract with a multi-argument constructor
 //!
 //! ```
 //! use soroban_sdk::{contract, contractimpl, BytesN, Env, Symbol, IntoVal};
+//!
 //! const DEPLOYED_WASM_WITH_CTOR: &[u8] = include_bytes!("../doctest_fixtures/contract_with_constructor.wasm");
+//!
 //! #[contract]
 //! pub struct Contract;
+//!
 //! #[contractimpl]
 //! impl Contract {
 //!     pub fn deploy_with_constructor(env: Env, wasm_hash: BytesN<32>) {
 //!         let salt = [1u8; 32];
 //!         let deployer = env.deployer().with_current_contract(salt);
-//!         // Deployed contract address is deterministic and can be accessed
-//!         // before deploying the contract.
-//!         let _ = deployer.deployed_address();
 //!         let contract_address = deployer.deploy_v2(
 //!              wasm_hash,
 //!              (1_u32, 2_i64),
 //!         );
+//!         // ...
 //!     }
 //! }
+//!
 //! #[test]
 //! fn test() {
 //! # }
@@ -82,6 +85,43 @@
 //! # #[cfg(not(feature = "testutils"))]
 //! # fn main() { }
 //! ```
+//!
+//! #### Derive before deployment what the address of a contract will be
+//!
+//! ```
+//! use soroban_sdk::{contract, contractimpl, Address, BytesN, Env, Symbol, IntoVal};
+//!
+//! #[contract]
+//! pub struct Contract;
+//!
+//! #[contractimpl]
+//! impl Contract {
+//!     pub fn deploy_contract_address(env: Env) -> Address {
+//!         let salt = [1u8; 32];
+//!         let deployer = env.deployer().with_current_contract(salt);
+//!         // Deployed contract address is deterministic and can be accessed
+//!         // before deploying the contract. It is derived from the deployer
+//!         // (the current contract's address) and the salt passed in above.
+//!         deployer.deployed_address()
+//!     }
+//! }
+//!
+//! #[test]
+//! fn test() {
+//! # }
+//! # #[cfg(feature = "testutils")]
+//! # fn main() {
+//!     let env = Env::default();
+//!     let contract_address = env.register(Contract, ());
+//!     let contract = ContractClient::new(&env, &contract_address);
+//!     assert_eq!(
+//!         contract.deploy_contract_address(),
+//!         Address::from_str(&env, "CBESJIMX7J53SWJGJ7WQ6QTLJI4S5LPPJNC2BNVD63GIKAYCDTDOO322"),
+//!     );
+//! }
+//! # #[cfg(not(feature = "testutils"))]
+//! # fn main() { }
+//! ```
 
 use crate::{
     env::internal::Env as _, unwrap::UnwrapInfallible, Address, Bytes, BytesN, ConstructorArgs,