From d49d3d2b301d28cad1d5986b30fa2849772cab11 Mon Sep 17 00:00:00 2001
From: Henry de Valence <hdevalence@hdevalence.ca>
Date: Mon, 17 Aug 2020 02:22:55 -0700
Subject: [PATCH] chain: tweak docs for JoinSplitData, ShieldedData

---
 zebra-chain/src/transaction/joinsplit.rs     | 9 ++++++++-
 zebra-chain/src/transaction/shielded_data.rs | 9 ++++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/zebra-chain/src/transaction/joinsplit.rs b/zebra-chain/src/transaction/joinsplit.rs
index b7c02502b..ded9b37ce 100644
--- a/zebra-chain/src/transaction/joinsplit.rs
+++ b/zebra-chain/src/transaction/joinsplit.rs
@@ -5,7 +5,14 @@ use crate::{
     sprout::JoinSplit,
 };
 
-/// A bundle of JoinSplit descriptions and signature data.
+/// A bundle of [`JoinSplit`] descriptions and signature data.
+///
+/// JoinSplit descriptions are optional, but Zcash transactions must include a
+/// JoinSplit signature and verification key if and only if there is at least one
+/// JoinSplit description. This wrapper type bundles at least one JoinSplit
+/// description with the required signature data, so that an
+/// `Option<JoinSplitData>` correctly models the presence or absence of any
+/// JoinSplit data.
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 pub struct JoinSplitData<P: ZkSnarkProof> {
     /// The first JoinSplit description, using proofs of type `P`.
diff --git a/zebra-chain/src/transaction/shielded_data.rs b/zebra-chain/src/transaction/shielded_data.rs
index c0c4f1cf7..f617a2ad8 100644
--- a/zebra-chain/src/transaction/shielded_data.rs
+++ b/zebra-chain/src/transaction/shielded_data.rs
@@ -6,7 +6,14 @@ use crate::{
     serialization::serde_helpers,
 };
 
-/// Sapling-on-Groth16 spend and output descriptions.
+/// A bundle of [`Spend`] and [`Output`] descriptions and signature data.
+///
+/// Spend and Output descriptions are optional, but Zcash transactions must
+/// include a binding signature if and only if there is at least one Spend *or*
+/// Output description. This wrapper type bundles at least one Spend or Output
+/// description with the required signature data, so that an
+/// `Option<ShieldedData>` correctly models the presence or absence of any
+/// shielded data.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct ShieldedData {
     /// Either a spend or output description.